Eclipse CDT

  • Revision slug: Eclipse_CDT
  • Revision title: Eclipse CDT
  • Revision id: 3419
  • Created:
  • Creator: Jonathan_Watt
  • Is current revision? No
  • Comment 130 words added, 163 words removed

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 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 projects that have their own build systems and complex project structure, like Mozilla. If you want to use an IDE with code assistance (syntax highlighting, autocomplete, call graph explorer, etc.) for Mozilla C++ development, then Eclipse CDT might be for you.

Note that Eclipse CDT will typically use in excess of 600 MB of RAM just to load an Eclipse project that has indexed a copy of the Mozilla source code. The functionality it provides makes this well worth it if you have enough RAM, but it may prevent you from using Eclipse if you don't.
This page assumes that you already have a copy of the Mozilla source and know how to build it (building is necessary to get a build log for Eclipse, as explained below).

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 correctly (as detailed below) it will do a much, much better job.

Before we get into what you need to do to get the code assistance features working well, here is some important background information so that you can make sense of the instructions that follow (and modify them to meet your own needs, if that's necessary).

Some important background

To be able to provide advanced 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 and build up a complete picture of the code. (What Eclipse is attempting to do when it "indexes" the source.) Static analysis involves parsing the source files, so naturally enough 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 this information, the code assistance that it can provide out of the box is pretty poor.

For projects the size and complexity of Mozilla, manually figuring out and configuring Eclipse with a valid set of defines and include paths for each source file would be impractical (there are lots of them, and they vary from one part of the code to another). Happily, Eclipse makes manual configuration unnecessary. Like some other IDEs, it provides a tool for projects that have their own build system so that it can collect the options that are passed to the compiler for each file compiled during an actual build.

The way that the Eclipse tool does the "compiler option discovery" is by scanning the console output for a real build looking for lines where a compiler was invoked. For each line that invokes a compiler, it tries to figure out which source file was being built, and to resolve any relative include paths. (Note that it may not always be possible to do one or both of these things if the build output doesn't identify which directory the compiler was being invoked from!) If Eclipse can successfully identify which source file was being built, then it can associate that file with any resolvable include paths along with any preprocessor defines and pre-include files that were passed to the compiler.

Note the requirements that Eclipse's method of compiler option discovery imposes on us. First, a build must be run from inside Eclipse in order for it to find the compiler options. For the build's console output to be useful, the build must not be parallelized (since that would result in overlapping and muddled lines from different build threads/processes) and the build must not be silenced/quietened. Finally, the build process must be explicitly instructed to output information that allows the directory that the compiler is being invoked from to be identified.

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.

Of course, the type of build that Eclipse requires is at odds with the way that most Mozilla developers use parallelized and silenced builds in order to minimize their build times.

The consequences of the above observations are that:

  • it is strongly recommended that you invoke your normal builds/rebuilds outside of Eclipse, from the command line
  • we will configure Eclipse's build step so that you can occasionally use it to manually trigger a special "build" that is purely for the purposes of setting/updating the compiler options Eclipse associates with each source file

(Not invoking your normal (re)builds from inside Eclipse does loose 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 loose.)

Create a usable build log

(This section comes first so that the build can be running while you install and configure Eclipse. You will probably only need to update the build log once every couple of months or so, if that.)

As explained above, we're going to set Eclipse's build step to trigger a special "build" that you will only use occasionally, whenever you need to set up or update the preprocessor defines, include paths and preinclude files that Eclipse associates with each source file (for use during its static analysis of the files).

Actually, rather than having Eclipse trigger a real build, we're going to trick it into reading a build log. The advantages of having it to read a log are that if something goes wrong, the log file can be reread by Eclipse much more quickly than doing a fresh build and, with a quick search and replace edit, the build log can also be reused when setting up Eclipse with your other Mozilla source trees.

First, note that the build log is going to contain include paths to a specific object directory in the file system. These include paths need to resolve whenever Eclipse reindexes the source, so the object directory for the build you're about to run should be your normal object directory (or one that will continue to exist and be updated for as long as you're using Eclipse with the source tree).

Second, the build needs to be a full rebuild, so delete that object directory now before you proceed.

That done, create a special mozconfig just for use when creating a build log for Eclipse (the following assumes the name .mozconfig-eclipse) and give it the following content.

# IMPORTANT!!! Do NOT use -j or -s in here!
# See https://developer.mozilla.org/en/Eclipse_CDT for why!

# IMPORTANT!!! We absolutely require make to output "Entering"/
# "Leaving" lines:
mk_add_options MOZ_MAKE_FLAGS="-w"

# IMPORTANT!!! Make sure this is your normal objdir, and emptied
# so you get a full rebuild:
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-debug

# A debug build is best so that Eclipse will index '#ifdef DEBUG'
# sections of the code:
ac_add_options --enable-debug --disable-optimize
ac_add_options --enable-debug-symbols

Be sure to set the name of the object directory on the MOZ_OBJDIR line to the name of your object directory!

Now create the build log by running the command:

MOZCONFIG=.mozconfig-eclipse make -f client.mk 1>build-for-eclipse.log 2>&1

While waiting for the build to finish, go on and install and setup Eclipse.

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, scheduled for released in June 2012.) Using Juno is important because the code assistances can be set up to work much better with the Mozilla code.

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" to remind you what version it is later.)

When you first run Eclipse, it will ask you to "Select a workspace" (a directory where the vast majority of the Eclipse files relating to the project(s) in the workspace will be stored). It is recommended that you have a separate workspace for each Mozilla source tree for which you create an Eclipse project, and that you choose a directory outside your Mozilla source tree. After you've selected an appropriate directory, click OK.

When the main Eclipse window opens, close the "Welcome" tab.

Now to update Juno to the latest nightly...

From Eclipse's "Help" menu select "Install New Software...", then in the "Install" window that opens, click "Add...". In the "Add Repository" dialog that opens, set "Name" to something like "Juno Nightly", "Location" to "http://download.eclipse.org/tools/cd...s/juno/nightly", then click "OK" to close the dialog. A "CDT Main Features" option should now have been added in the "Install" window. Tick this (so all of its sub-options will then be ticked), click "Next" twice, accept the license agreement, and then click "Finish". Eclipse will now update itself.

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

Creating an Eclipse project

Whenever you create a new workspace for Mozilla source, you should turn off the following two settings in Eclipse's global preferences before you create a project in that workspace:

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

This is because we won't be ready for the CPU and RAM intensive indexer to run until we've set up various project setting, and as you'll discover below, we don't want Eclipse to build automatically.

With those settings disabled, select "File > New > Makefile Project with Existing Code". In the "Import Existing Code" window that opens, first set the "Existing Code Location" to the root of your Mozilla source tree, and only then enter a meaningful Project Name that will associate the project with the source tree (this order is because, annoyingly, selecting a directory overwrites the Project Name). Select an appropriate Toolchain (e.g. "MacOSX GCC"), make sure that "I want to try new and upcoming version of Scanner Discovery in CDT 9.0" is checked, then click Finish.

The status bar at the bottom right of the window should now show that Eclipse is "Refreshing the workspace" (gather 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 then wait for the "Refreshing workspace" item to be replaced by an "indexing" item. When it is, click the little red box to cancel it. (This is necessary because for some reason after the initial refresh Eclipse ignores the fact that we disabled "Automatically update the index".)

Next, so that the indexer will give better results (and run faster), you should set filters to exclude from the source tree the .hg directory (yes, it doesn't show in the Project Explorer, but Eclipse still indexes it!) and all object directories except the one you selected above when creating the build log (one object directory is needed to resolve include paths for various generated and copied headers). To do this, open the project properties and select "Resource > Resource Filters" on the left. Use the Add button to add the following filters:

  • Add an exclude filter for folders with a Project Relative Path matching ".hg".
  • Add an exclude filter for folders with a Project Relative Path matching the regular expression "obj(?!-debug(?:$|/)).+". Or at least something like that - that particular regular expression will exclude all object directories except "obj-debug", so if that's not the name of the object directory that you want to exclude you're have to adjust the regular expression as necessary.

If you have any other directories in the source tree (Xcode or MSVC project directories for example) then add filters to exclude those too, then Close. After Eclipse finishes processing these changes, those directories should disappear from the Project Explorer tab on the left.

With the project created, go to "Project > Properties > C/C++ General > Preprocessor include Paths, Macros etc.". Select the Providers tab. Tick the "CDT GCC Build Output Parser". Make sure that "CDT GCC Build Output Parser" is highlighted, then in its "Language Settings Provider Options" below, make sure that "Share setting entries between projects (global provider)" is not ticked. Repeat for "CDT GCC Builtin Compiler Settings".

Open "Project > Properties" and select "C/C++ Build". Select the "Builder Settings" tab, untick "Use default build command", set the build command to "cat build-for-eclipse.log", and set the build directory to "${ProjDirPath}/." Select the "Behaviour" tab, delete the word "all" from the "Build (incremental build)" field, and disable the Clean checkbox.

Using the build log

Hopefully it won't be too long now before the build that you started during the steps above has finish creating the build log we need to get Eclipse's static analysis working properly.

Reading in the build log

Once the build has finished, check the end of the log file to make sure that the build completed successfully, and to double check that it contains the "Entering"/"Leaving" lines that Eclipse needs. A handy way to do this is to print the last few lines using:

tail build-for-eclipse.log

If everything is okay, and if you configured the build commands and build directory as directed above, then click the Build button (a hammer symbol) or select "Project > Build Project" from the main menu. If you select the "Console" tab at the bottom of the window, you should now see the contents of the build log flying by as Eclipse processes them.

Once you see the end of the build log in the Console tab, it's time to index the source! Right click the project 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-20 minutes on a decent developer machine for a full rebuild of the index. Once the indexing has finished you should find that Eclipse's code assistance works much better. :-)

XXX can "Automatically update the index" be turned back on now?

Reusing the build log

It is possible to reuse the build log to set up Eclipse with other copies of the Mozilla source rather than doing a special build for each of your source trees. You just need to do a quick search and replace in the log file first. Specifically:

  • replace the absolute path to the root of the original source tree with the absolute path to the root of the tree you're setting up Eclipse with
  • replace the name of the object directory, if necessary

Your editor should tell you it's replaced about 10,000+ lines, then you're good to go.

Refreshing the build log

In my experience (Jonathan Watt's, during 2011), it seems to take several months before changes to the Mozilla build system cause the compiler options that Eclipse has associated with the source to become noticeably stale. When that happens, just create a new build log using the steps above, read it in, and rebuild the index.

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 set Eclipse to run a build that is NOT parallelized, NOT silenced, and that IS built with -w to output "Entering"/"Leaving" lines, Eclipse's code assistance will be seriously degraded when you build from inside Eclipse (see above for why!). Since avoiding these problems would require Eclipse to do verbose, slow rebuilds of the entire tree each time you hit the Build button, it is strongly recommended that you do NOT configure Eclipse to trigger your normal (re)builds, and that instead you (re)build outside Eclipse using your console. In other words, rather than following the instructions below to configure Eclipse's "build" action to build the source, its almost certainly better for you to follow the instructions above to make the "build" action read in an appropriate build log file.

Nevertheless, if you understand the above you still want to configure Eclipse's "Build" button to run 'make -f client.mk', then this is how you would do it...

Select "Project > Properties > C/C++ Build" and then select the "Builder Settings" tab. Untick "Use default build command" and set the "Build command" to "make -w -f client.mk". Set "Build directory" to "${ProjDirPath}/.". Now select the Behaviour tab and remove the "all" from the "Build (Incremental build)" field.

Next, select "Project > Properties > C/C++ Build > Build Variables", and add a variable "MOZCONFIG" and set it to the name 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 that caused the problem. 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 relibably 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 i don't think Eclipse requires this any more:

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

Known Issues

There are various knows limitations and bugs when it comes to using Eclipse with Mozilla.

Mac Framework include directories

On Mac it is know that Eclipse does not pick up the Framework include directories as it should, so some headers will be unresolved and cause problems for the indexer.

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. This is just one of those things that it's best to put up with. Some source and header files are copied to the object directory so copies exist in both places. In the case of include files, some source files include the header from the source directory, while others include it from the object directory. Setting up a resource filter to exclude the copies in the object directory would break indexing for the source files that include the headers from there.

FAQ

Here are some questions that have been/may be asked.

Is there a Mercurial plugin for Eclipse?

There is MercurialEclipse, but probably most Mozilla developers will probably just prefer to just 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.

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

Yes, but Eclipse doesn't currently support it. Specifically, the IDE could be used to invoke the external build system, while using something like LD_PRELOAD to load its own little library into all the executables that are invoked as part of the build process. This library could then check whether the executable is a compiler instance and, if so, use the processes' current working directory and the arguments that were passed to it to obtain the information it needs for each source file. This would massively simplify the instructions above since it would be possible to use Eclipse to trigger your builds whenever you liked, without requiring a log file, and without requiring you to avoid parallelized or silenced builds.

Troubleshooting

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

Problem Occurred (Java heap space)

If you get a "Problem Occurred" error window and it mentions "Java heap space" when you click on "Details", try increasing the heap space. This problem is most likely to occur during indexing.

It seems there may currently be a serious memory leak in the sd90 indexing code, and that indexing may sometimes cause the memory to shoot through the roof no matter how big you make the heap space. If that's the case for you, please let Jonathan Watt know.

Resource is out of sync with the file system

If you get get the message "Resource is out of sync with the file system", refresh the project (or an individual directory/file) using the Refresh item from the context menu for the project (or directory/file) in the Project Explorer tab. You may also want no enable "General > Workspace > Refresh automatically".

Old

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

Initial setup

The following instructions are for Linux. If you have experience with Win32, please note it here.

  • Install Eclipse IDE for C/C++ Developers.
  • Obtain a clean copy of the Mozilla source.
  • Make a buildable Mozilla tree with the object files in an objdir. For example, sources in "src/", object files in "src/obj-debug".
  • Things will be a little quicker if you delete any unnecessary files from the source directory, e.g., "*~" emacs backups, "*.rej", "*.orig" and ".#*" patch detritus.
  • Start Eclipse and when prompted to "Select a workspace" just accept the default - we'll give our Mozilla project(s) their own workspace(s) rather than using this one anyway.
  • Fire up Eclipse and do File > New > C++ Project to start the C++ Project wizard.
    • Enter a meaningful project name identifying the Mozilla source tree this project will manage. (The Eclipse help docs say "do not use spaces or special characters in the project name".)
    • Uncheck the "Use default location" box, and enter the path of the directory containing the Mozilla source.
    • Pick "Makefile Project"
  • Now you can finish the wizard. You should get a Project view in the left with a directory tree you can browse to find files to edit. (Tip: Ctrl-F brings up a fast-find textbox for quick selection of files from opened directories.)
  • Doubleclick on a file to edit it. It should be syntax highlighted. There should be an outline in the right-hand pane that shows the gross constructs in the file. (Sometimes elements are missing because the parser was recovering from an error --- this view doesn't parse include files).
  • You can tweak preferences to improve your life: menu Window | Preferences
    • In the General | Keys page, in the Modify tab, you can select the Emacs scheme if your fingers demand it
  • Turn off "Build Automatically" in the Project menu.

Editing Tips

Alt-/ emacs-style abbrev completion just works.

In the default key bindings, ctrl-J does incremental search. Some users find that they like to use ctrl-G for "next match" (because Firefox does) but in Eclipse that tries to locate the definition of an identifier, which can be very slow in Mozilla with the CDT. You may want to rebind ctrl-G to "next match" if it isn't already so bound.

You probably need to adjust the CDT editor preferences to always use spaces instead of tabs, and to indent by 2 spaces.

Eclipse doesn't exactly provide the emacs buffers setup, but it does go some way towards it. Press ctrl-E to get a list of active editors; typing into it gives you autocompletion of the editor/buffer name for you to switch to.

Extra CDT features

Building

You can configure CDT to build Mozilla by calling "make". Select the project in the project view, right click, choose Properties, C/C++ Make project, then you can configure how "make" is called. (For example, you may want to input the command for building your project as "make -f client.mk build".) Do a build by choosing Project | Build Project in the menus. It works OK but the obvious approach does a full build which is quite slow in Mozilla (we go through all directories twice, once for exports and once for the real build).

If you're brave you can turn on "auto build on save" in the project properties under "C++ Make Project" in the "Make Builder" tab, and/or by turning on Build Automatically in the project menu. I don't recommend it.

Build output appears in the Console view near the bottom of the window. Eclipse will do an OK job of matching compiler errors/warnings to source lines if you configure your Mozilla build with the gcc option "-fmessage-length=0". Just add the lines

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

to your .mozconfig. Errors and warnings will be marked in the source when you open an affected file. They will also appear in the "Problems" view near the bottom of the window.

Be aware that Eclipse's parsing of the build output can be screwed up if you use parallel make.

Intelligent Code Navigation

The CDT offers intelligent code completion, and source navigation and indexing. These features are currently too slow and have a few bugs that stop me from using them regularly with Mozilla, but they're fun to play with.

First you have to teach the Eclipse parser which files get built and with what options. If you do a clean build from Eclipse and it doesn't get screwed up, Eclipse will discover all the include files/directories and predefined preprocessor symbols for each file in the project. These are visible via Properties (in the context menu) for each file. Eclipse will also learn which files get built and which don't. Maybe a more reliable way to teach Eclipse this information is to do a clean build, redirect the output to a file, then in project properties "C++ Make Project" Discovery Options you can specify the build log file and choose "Load".

Now you should be able to use intelligent code completion. Start typing an identifier and press ctrl-space. You should get a popup list of the completions that are valid in the current scope --- including global functions and variables, applicable "this" members, members if you're completing a member access, and even macros. Unfortunately in the current CDT this always does a parse of the current translation unit up to the completion point, which takes several seconds for a large Mozilla file with a decent number of includes, so this isn't good.

You should also be able to navigate within the current compilation unit by holding down ctrl and then clicking on an identifier to jump to its definition. Again this requires parsing of the compilation unit.

For really slick navigation you need to index the Mozilla project by turning on the indexer (Project properties, C++ Make Project, C++ indexer). Starting with Eclipse 3.3.2, the indexation process was greatly improved and is worth executing once.

If you like living dangerously, in Preferences | C/C++ you can select "follow #includes when parsing working copies". Eclipse will then follow #includes when it does parsing to update the outline view. This slows things down massively and is not recommended, but without it, many of our macros will not be defined and either cause syntax errors in the quick parser which cause some constructs to be omitted from the outline due to error recovery, or some constructs will not be parsed at all because they're #ifdefed and Eclipse doesn't know that the macro is defined.

Debugging

You can use Eclipse as a front end to gdb. It simplifies debugging and variable watching.

First, you need to create a debug configuration.

 Select Run->Open Debug Dialog… from the Eclipse menu
 Right-click on C/C++ Local Application and select New
 Project: firefox (or select your project name)
 C/C++ Application: (select browse and choose mozilla/../obj-i686-pc-linux-gnu/dist/bin/firefox-bin)

Specific configuration

  1. In the Arguments tab, change the working directory to mozilla/../obj-i686-pc-linux-gnu/dist/bin/
  2. In the Debugger tab, remove the checkbox on "Stop on startup at:"
  3. In the Environment tab, create two variables (make sure you trim the names and values)
 Name:  LD_LIBRARY_PATH
 Value: .:./plugins:.
 
 Name:  LIBRARY_PATH
 Value: .:./components:.
GDB Timeouts

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

Build Parallelism

You can use distcc and the MOZ_MAKE_FLAGS build variable to distribute the compilation across a network. This greatly improves the speed of the build. The complete informations are available in the Mozilla Team Documentation - distcc.

CDT Issues

The CDT has some problems with Mozilla that need to be worked on.

  • Code completion and other operations that require a full parse tree are really slow because they parse the compilation unit from scratch every time. This can be fixed -- there is a plan. But it's quite a lot of work.
  • The parser has bugs. I get a few internal parser errors when parsing the common Mozilla include files that use slightly tricky constructs (e.g., nsCOMPtr). Some of these bugs should be easy to fix, others maybe not. Apparently these bugs are only in the "old" parser which is deprecated and will be completely replaced by the "new" parser, "soon", so it's not really worth working on these bugs.
  • It would be nice if Eclipse could 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've 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.
  • Debugging.
  • Some editing operations get sluggish when you have lots of files open (say, more than 20).
  • The GDB thread terminates unexpectedly and detaches from the Firefox bin. This is caused by the breakpoints currently set. When you restart your Eclipse environment and face such issue. Delete and readd the breakpoints in your list.

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 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 projects that have their own build systems and complex project structure, like Mozilla. If you want to use an IDE with code assistance (syntax highlighting, autocomplete, call graph explorer, etc.) for Mozilla C++ development, then Eclipse CDT might be for you.</p>
<div class="warning">Note that Eclipse CDT will typically use in excess of 600 MB of RAM just to load an Eclipse project that has indexed a copy of the Mozilla source code. The functionality it provides makes this well worth it if you have enough RAM, but it may prevent you from using Eclipse if you don't.</div>
<div class="warning">This page assumes that you already <a href="/En/Simple_Firefox_build" title="https://developer.mozilla.org/En/Simple_Firefox_build">have a copy of the Mozilla source and know how to build it</a> (building is necessary to get a build log for Eclipse, as explained below).</div>
<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 correctly (as detailed below) it will do a much, much better job.</p>
<p>Before we get into what you need to do to get the code assistance features working well, here is some important background information so that you can make sense of the instructions that follow (and modify them to meet your own needs, if that's necessary).</p>
<h3>Some important background</h3>
<p>To be able to provide advanced 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 and build up a complete picture of the code. (What Eclipse is attempting to do when it "indexes" the source.) Static analysis involves parsing the source files, so naturally enough 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 this information, the code assistance that it can provide out of the box is pretty poor.<br> <br> For projects the size and complexity of Mozilla, manually figuring out and configuring Eclipse with a valid set of defines and include paths for each source file would be impractical (there are <em>lot</em>s of them, and they vary from one part of the code to another). Happily, Eclipse makes manual configuration unnecessary. Like some other IDEs, it provides a tool for projects that have their own build system so that it can collect the options that are passed to the compiler for each file compiled during an actual build.</p>
<p>The way that the Eclipse tool does the "compiler option discovery" is by scanning the console output for a real build looking for lines where a compiler was invoked. For each line that invokes a compiler, it tries to figure out which source file was being built, and to resolve any relative include paths. <em>(Note that it may not always be possible to do one or both of these things if the build output doesn't identify which directory the compiler was being invoked from!)</em> If Eclipse can successfully identify which source file was being built, then it can associate that file with any resolvable include paths along with any preprocessor defines and pre-include files that were passed to the compiler.</p>
<p>Note the requirements that Eclipse's method of compiler option discovery imposes on us. First, a build must be run from inside Eclipse in order for it to find the compiler options. For the build's console output to be useful, the build must not be parallelized (since that would result in overlapping and muddled lines from different build threads/processes) and the build must not be silenced/quietened. Finally, the build process must be explicitly instructed to output information that allows the directory that the compiler is being invoked from to be identified.</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>Of course, the type of build that Eclipse requires is at odds with the way that most Mozilla developers use parallelized and silenced builds in order to minimize their build times.</p>
<p>The consequences of the above observations are that:</p>
<div class="warning"> <ul> <li>it is strongly recommended that you invoke your normal builds/rebuilds outside of Eclipse, from the command line</li> <li>we will configure Eclipse's build step so that you can <strong><u>occasionally</u></strong> use it to manually trigger a special "build" that is purely for the purposes of setting/updating the compiler options Eclipse associates with each source file</li> </ul>
</div>
<p>(Not invoking your normal (re)builds from inside Eclipse does loose 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 loose.)</p>
<h2>Create a usable build log</h2>
<p>(This section comes first so that the build can be running while you install and configure Eclipse. You will probably only need to update the build log once every couple of months or so, if that.)</p>
<p>As explained above, we're going to set Eclipse's build step to trigger a special "build" that you will only use occasionally, whenever you need to set up or update the preprocessor defines, include paths and preinclude files that Eclipse associates with each source file (for use during its static analysis of the files).</p>
<p>Actually, rather than having Eclipse trigger a real build, we're going to trick it into reading a build log. The advantages of having it to read a log are that if something goes wrong, the log file can be reread by Eclipse much more quickly than doing a fresh build and, with a quick search and replace edit, the build log can also be reused when setting up Eclipse with your other Mozilla source trees.</p>
<p>First, note that the build log is going to contain include paths to a specific object directory in the file system. These include paths need to resolve whenever Eclipse reindexes the source, so the object directory for the build you're about to run should be your normal object directory (or one that will continue to exist and be updated for as long as you're using Eclipse with the source tree).</p>
<p>Second, the build needs to be a full rebuild, so delete that object directory now before you proceed.</p>
<p>That done, create a special mozconfig just for use when creating a build log for Eclipse (the following assumes the name .mozconfig-eclipse) and give it the following content.</p>
<pre># IMPORTANT!!! Do NOT use -j or -s in here!
# See https://developer.mozilla.org/en/Eclipse_CDT for why!

# IMPORTANT!!! We absolutely require make to output "Entering"/
# "Leaving" lines:
mk_add_options MOZ_MAKE_FLAGS="-w"

# IMPORTANT!!! Make sure this is your normal objdir, and emptied
# so you get a full rebuild:
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-debug

# A debug build is best so that Eclipse will index '#ifdef DEBUG'
# sections of the code:
ac_add_options --enable-debug --disable-optimize
ac_add_options --enable-debug-symbols
</pre>
<p>Be sure to set the name of the object directory on the MOZ_OBJDIR line to the name of your object directory!</p>
<p>Now create the build log by running the command:</p>
<pre>MOZCONFIG=.mozconfig-eclipse make -f client.mk 1&gt;build-for-eclipse.log 2&gt;&amp;1
</pre>
<p>While waiting for the build to finish, go on and install and setup Eclipse.</p>
<h2 name="Getting_Started">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, scheduled for released in June 2012.) Using Juno is important because the code assistances can be set up to work much better with the Mozilla code.<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" to remind you what version it is later.)</p>
<p>When you first run Eclipse, it will ask you to "Select a workspace" (a directory where the vast majority of the Eclipse files relating to the project(s) in the workspace will be stored). It is recommended that you have a separate workspace for each Mozilla source tree for which you create an Eclipse project, and that you choose a directory outside your Mozilla source tree. After you've selected an appropriate directory, click OK.</p>
<p>When the main Eclipse window opens, close the "Welcome" tab.</p>
<p>Now to update Juno to the latest nightly...</p>
<p>From Eclipse's "Help" menu select "Install New Software...", then in the "Install" window that opens, click "Add...". In the "Add Repository" dialog that opens, set "Name" to something like "Juno Nightly", "Location" to "<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>", then click "OK" to close the dialog. A "CDT Main Features" option should now have been added in the "Install" window. Tick this (so <em>all</em> of its sub-options will then be ticked), click "Next" twice, accept the license agreement, and then click "Finish". Eclipse will now update itself.</p>
<p>Troubleshooting: If you get an error when trying to add "Juno Nightly", try clicking "Available Software Sites" in the "Install" window, and untick "Juno", make sure "Juno Nightly" is ticked, and then highlight "Juno Nightly", click "Reload", "OK", and then try again.</p>
<h2>Creating an Eclipse project</h2>
<p>Whenever you create a new workspace for Mozilla source, you should turn off the following two settings in Eclipse's global preferences before you create 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>This is because we won't be ready for the CPU and RAM intensive indexer to run until we've set up various project setting, and as you'll discover below, we don't want Eclipse to build automatically.</p>
<p>With those settings disabled, select "File &gt; New &gt; Makefile Project with Existing Code". In the "Import Existing Code" window that opens, first set the "Existing Code Location" to the root of your Mozilla source tree, and only then enter a meaningful Project Name that will associate the project with the source tree (this order is because, annoyingly, selecting a directory overwrites the Project Name). Select an appropriate Toolchain (e.g. "MacOSX GCC"), make sure that "I want to try new and upcoming version of Scanner Discovery in CDT 9.0" is checked, then click Finish.</p>
<p>The status bar at the bottom right of the window should now show that Eclipse is "Refreshing the workspace" (gather 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 then wait for the "Refreshing workspace" item to be replaced by an "indexing" item. When it is, click the little red box to cancel it. (This is necessary because for some reason after the initial refresh Eclipse ignores the fact that we disabled "Automatically update the index".)</p>
<p>Next, so that the indexer will give better results (and run faster), you should set filters to exclude from the source tree the .hg directory (yes, it doesn't show in the Project Explorer, but Eclipse still indexes it!) and all object directories except the one you selected above when creating the build log (one object directory is needed to resolve include paths for various generated and copied headers). To do this, open the project properties and select "Resource &gt; Resource Filters" on the left. Use the Add button to add the following filters:</p>
<ul> <li>Add an exclude filter for folders with a Project Relative Path matching ".hg".</li> <li>Add an exclude filter for folders with a Project Relative Path matching the regular expression "obj(?!-debug(?:$|/)).+". Or at least something like that - that particular regular expression will exclude all object directories except "obj-debug", so if that's not the name of the object directory that you want to exclude you're have to adjust the regular expression as necessary.</li>
</ul>
<p>If you have any other directories in the source tree (Xcode or MSVC project directories for example) then add filters to exclude those too, then Close. After Eclipse finishes processing these changes, those directories should disappear from the Project Explorer tab on the left.</p>
<p>With the project created, go to "Project &gt; Properties &gt; C/C++ General &gt; Preprocessor include Paths, Macros etc.". Select the Providers tab. Tick the "CDT GCC Build Output Parser". Make sure that "CDT GCC Build Output Parser" is highlighted, then in its "Language Settings Provider Options" below, make sure that "Share setting entries between projects (global provider)" is not ticked. Repeat for "CDT GCC Builtin Compiler Settings".</p>
<p>Open "Project &gt; Properties" and select "C/C++ Build". Select the "Builder Settings" tab, untick "Use default build command", set the build command to "cat build-for-eclipse.log", and set the build directory to "${ProjDirPath}/." Select the "Behaviour" tab, delete the word "all" from the "Build (incremental build)" field, and disable the Clean checkbox.</p>
<h2>Using the build log</h2>
<p>Hopefully it won't be too long now before the build that you started during the steps above has finish creating the build log we need to get Eclipse's static analysis working properly.</p>
<h3>Reading in the build log</h3>
<p>Once the build has finished, check the end of the log file to make sure that the build completed successfully, and to double check that it contains the "Entering"/"Leaving" lines that Eclipse needs. A handy way to do this is to print the last few lines using:</p>
<pre>tail build-for-eclipse.log
</pre>
<p>If everything is okay, and if you configured the build commands and build directory as directed above, then click the Build button (a hammer symbol) or select "Project &gt; Build Project" from the main menu. If you select the "Console" tab at the bottom of the window, you should now see the contents of the build log flying by as Eclipse processes them.</p>
<p>Once you see the end of the build log in the Console tab, it's time to index the source! Right click the project 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-20 minutes on a decent developer machine for a full rebuild of the index. Once the indexing has finished you should find that Eclipse's code assistance works much better. :-)</p>
<p>XXX can "Automatically update the index" be turned back on now?</p>
<h3>Reusing the build log</h3>
<p>It is possible to reuse the build log to set up Eclipse with other copies of the Mozilla source rather than doing a special build for each of your source trees. You just need to do a quick search and replace in the log file first. Specifically:</p>
<ul> <li>replace the absolute path to the root of the original source tree with the absolute path to the root of the tree you're setting up Eclipse with</li> <li>replace the name of the object directory, if necessary</li>
</ul>
<p>Your editor should tell you it's replaced about 10,000+ lines, then you're good to go.</p>
<h3>Refreshing the build log</h3>
<p>In my experience (<a href="/User:Jonathan_Watt" title="User:Jonathan Watt">Jonathan Watt</a>'s, during 2011), it seems to take several months before changes to the Mozilla build system cause the compiler options that Eclipse has associated with the source to become noticeably stale. When that happens, just create a new build log using the steps above, read it in, and rebuild the index.</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 set Eclipse to run a build that is NOT parallelized, NOT silenced, and that IS built with -w to output "Entering"/"Leaving" lines, Eclipse's code assistance will be seriously degraded when you build from inside Eclipse (see above for why!). Since avoiding these problems would require Eclipse to do verbose, slow rebuilds of the entire tree each time you hit the Build button, it is strongly recommended that you do NOT configure Eclipse to trigger your normal (re)builds, and that instead you (re)build outside Eclipse using your console. In other words, rather than following the instructions below to configure Eclipse's "build" action to build the source, its almost certainly better for you to follow the instructions above to make the "build" action read in an appropriate build log file.</div>
<p>Nevertheless, if you understand the above you still want to configure Eclipse's "Build" button to run 'make -f client.mk', then this is how you would do it...</p>
<p>Select "Project &gt; Properties &gt; C/C++ Build" and then select the "Builder Settings" tab. Untick "Use default build command" and set the "Build command" to "make -w -f client.mk". Set "Build directory" to "${ProjDirPath}/.". Now select the Behaviour tab and remove the "all" from the "Build (Incremental build)" field.</p>
<p>Next, select "Project &gt; Properties &gt; C/C++ Build &gt; Build Variables", and add a variable "MOZCONFIG" and set it to the name 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 that caused the problem. 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 relibably 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 i don't think Eclipse requires this any more:</p>
<pre>export CFLAGS="-fmessage-length=0"
export CPPFLAGS="-fmessage-length=0"
</pre>
<h2>Known Issues</h2>
<p>There are various knows limitations and bugs when it comes to using Eclipse with Mozilla.</p>
<h3>Mac Framework include directories</h3>
<p>On Mac it is know that <a class="link-https" href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=69529" title="https://bugs.eclipse.org/bugs/show_bug.cgi?id=69529">Eclipse does not pick up the Framework include directories</a> as it should, so some headers will be unresolved and cause problems for the indexer.</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. This is just one of those things that it's best to put up with. Some source and header files are copied to the object directory so copies exist in both places. In the case of include files, some source files include the header from the source directory, while others include it from the object directory. Setting up a resource filter to exclude the copies in the object directory would break indexing for the source files that include the headers from there.</p>
<h2>FAQ</h2>
<p>Here are some questions that have been/may be asked.</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 just 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>Isn't there a better method of compiler option discovery?</h3>
<p>Yes, but Eclipse doesn't currently support it. Specifically, the IDE could be used to invoke the external build system, while using something like LD_PRELOAD to load its own little library into all the executables that are invoked as part of the build process. This library could then check whether the executable is a compiler instance and, if so, use the processes' current working directory and the arguments that were passed to it to obtain the information it needs for each source file. This would massively simplify the instructions above since it would be possible to use Eclipse to trigger your builds whenever you liked, without requiring a log file, and without requiring you to avoid parallelized or silenced builds.</p>
<h2>Troubleshooting</h2>
<p>Here is a list of problems people have encountered, and suggestions for solutions.</p>
<h3>Problem Occurred (Java heap space)</h3>
<p>If you get a "Problem Occurred" error window and it mentions "Java heap space" when you click on "Details", try <a class="external" href="http://wiki.eclipse.org/eclipse.ini" title="http://wiki.eclipse.org/eclipse.ini">increasing the heap space</a>. This problem is most likely to occur during indexing.</p>
<p>It seems there may currently be a serious memory leak in the sd90 indexing code, and that indexing may sometimes cause the memory to shoot through the roof no matter how big you make the heap space. If that's the case for you, please let <a href="/User:Jonathan_Watt" title="User:Jonathan Watt">Jonathan Watt</a> know.</p>
<h3>Resource is out of sync with the file system</h3>
<p>If you get get the message "Resource is out of sync with the file system", refresh the project (or an individual directory/file) using the Refresh item from the context menu for the project (or directory/file) in the Project Explorer tab. You may also want no enable "General &gt; Workspace &gt; Refresh automatically".</p>
<h2>Old</h2>
<p>Everything that follows is old content that will be deleted (or integrated in).</p>
<h3>Initial setup</h3>
<p>The following instructions are for Linux. If you have experience with Win32, please note it here.</p>
<ul> <li>Install <a class="external" href="http://www.eclipse.org/downloads/" title="http://www.eclipse.org/downloads/">Eclipse IDE for C/C++ Developers</a>.</li> <li>Obtain a <a href="/En/Developer_Guide/Source_Code/Mercurial" title="En/Developer Guide/Source Code/Mercurial">clean copy of the Mozilla source</a>.</li> <li>Make a buildable Mozilla tree with the object files in an objdir. For example, sources in "src/", object files in "src/obj-debug".</li> <li>Things will be a little quicker if you delete any unnecessary files from the source directory, e.g., "*~" emacs backups, "*.rej", "*.orig" and ".#*" patch detritus.</li> <li>Start Eclipse and when prompted to "Select a workspace" just accept the default - we'll give our Mozilla project(s) their own workspace(s) rather than using this one anyway.</li> <li>Fire up Eclipse and do <code>File &gt; New &gt; C++ Project</code> to start the C++ Project wizard. <ul> <li>Enter a meaningful project name identifying the Mozilla source tree this project will manage. (The Eclipse help docs say "<a class="external" href="http://help.eclipse.org/helios/topic/org.eclipse.platform.doc.user/gettingStarted/qs-07b.htm" title="http://help.eclipse.org/helios/topic/org.eclipse.platform.doc.user/gettingStarted/qs-07b.htm">do not use spaces or special characters in the project name</a>".)</li> <li>Uncheck the "Use default location" box, and enter the path of the directory containing the Mozilla source.</li> <li>Pick "Makefile Project"</li> </ul> </li> <li>Now you can finish the wizard. You should get a Project view in the left with a directory tree you can browse to find files to edit. (Tip: Ctrl-F brings up a fast-find textbox for quick selection of files from opened directories.)</li> <li>Doubleclick on a file to edit it. It should be syntax highlighted. There should be an outline in the right-hand pane that shows the gross constructs in the file. (Sometimes elements are missing because the parser was recovering from an error --- this view doesn't parse include files).</li> <li>You can tweak preferences to improve your life: menu Window | Preferences <ul> <li>In the General | Keys page, in the Modify tab, you can select the Emacs scheme if your fingers demand it</li> </ul> </li> <li>Turn off "Build Automatically" in the Project menu.</li>
</ul>
<h3 name="Editing_Tips">Editing Tips</h3>
<p>Alt-/ emacs-style abbrev completion just works.</p>
<p>In the default key bindings, ctrl-J does incremental search. Some users find that they like to use ctrl-G for "next match" (because Firefox does) but in Eclipse that tries to locate the definition of an identifier, which can be very slow in Mozilla with the CDT. You may want to rebind ctrl-G to "next match" if it isn't already so bound.</p>
<p>You probably need to adjust the CDT editor preferences to always use spaces instead of tabs, and to indent by 2 spaces.</p>
<p>Eclipse doesn't exactly provide the emacs buffers setup, but it does go some way towards it. Press ctrl-E to get a list of active editors; typing into it gives you autocompletion of the editor/buffer name for you to switch to.</p>
<h3 name="Extra_CDT_features">Extra CDT features</h3>
<h4 name="Building">Building</h4>
<p>You can configure CDT to build Mozilla by calling "make". Select the project in the project view, right click, choose Properties, C/C++ Make project, then you can configure how "make" is called. (For example, you may want to input the command for building your project as "make -f client.mk build".) Do a build by choosing Project | Build Project in the menus. It works OK but the obvious approach does a full build which is quite slow in Mozilla (we go through all directories twice, once for exports and once for the real build).</p>
<p>If you're brave you can turn on "auto build on save" in the project properties under "C++ Make Project" in the "Make Builder" tab, and/or by turning on Build Automatically in the project menu. I don't recommend it.</p>
<p>Build output appears in the Console view near the bottom of the window. Eclipse will do an OK job of matching compiler errors/warnings to source lines if you configure your Mozilla build with the gcc option "-fmessage-length=0". Just add the lines</p>
<pre class="eval">export CFLAGS="-fmessage-length=0"
export CPPFLAGS="-fmessage-length=0"
</pre>
<p>to your .mozconfig. Errors and warnings will be marked in the source when you open an affected file. They will also appear in the "Problems" view near the bottom of the window.</p>
<p>Be aware that Eclipse's parsing of the build output can be screwed up if you use parallel make.</p>
<h4 name="Intelligent_Code_Navigation">Intelligent Code Navigation</h4>
<p>The CDT offers intelligent code completion, and source navigation and indexing. These features are currently too slow and have a few bugs that stop me from using them regularly with Mozilla, but they're fun to play with.</p>
<p>First you have to teach the Eclipse parser which files get built and with what options. If you do a clean build from Eclipse and it doesn't get screwed up, Eclipse will discover all the include files/directories and predefined preprocessor symbols for each file in the project. These are visible via Properties (in the context menu) for each file. Eclipse will also learn which files get built and which don't. Maybe a more reliable way to teach Eclipse this information is to do a clean build, redirect the output to a file, then in project properties "C++ Make Project" Discovery Options you can specify the build log file and choose "Load".</p>
<p>Now you should be able to use intelligent code completion. Start typing an identifier and press ctrl-space. You should get a popup list of the completions that are valid in the current scope --- including global functions and variables, applicable "this" members, members if you're completing a member access, and even macros. Unfortunately in the current CDT this always does a parse of the current translation unit up to the completion point, which takes several seconds for a large Mozilla file with a decent number of includes, so this isn't good.</p>
<p>You should also be able to navigate within the current compilation unit by holding down ctrl and then clicking on an identifier to jump to its definition. Again this requires parsing of the compilation unit.</p>
<p>For really slick navigation you need to index the Mozilla project by turning on the indexer (Project properties, C++ Make Project, C++ indexer). Starting with Eclipse 3.3.2, the indexation process was greatly improved and is worth executing once.</p>
<p>If you like living dangerously, in Preferences | C/C++ you can select "follow #includes when parsing working copies". Eclipse will then follow #includes when it does parsing to update the outline view. This slows things down massively and is not recommended, but without it, many of our macros will not be defined and either cause syntax errors in the quick parser which cause some constructs to be omitted from the outline due to error recovery, or some constructs will not be parsed at all because they're #ifdefed and Eclipse doesn't know that the macro is defined.</p>
<h4 name="Debugging">Debugging</h4>
<p>You can use Eclipse as a front end to gdb. It simplifies debugging and variable watching.</p>
<p>First, you need to create a debug configuration.</p>
<pre class="eval"> Select Run-&gt;Open Debug Dialog… from the Eclipse menu
 Right-click on C/C++ Local Application and select New
 Project: firefox (or select your project name)
 C/C++ Application: (select browse and choose mozilla/../obj-i686-pc-linux-gnu/dist/bin/firefox-bin)
</pre>
<p>Specific configuration</p>
<ol> <li>In the Arguments tab, change the working directory to mozilla/../obj-i686-pc-linux-gnu/dist/bin/</li> <li>In the Debugger tab, remove the checkbox on "Stop on startup at:"</li> <li>In the Environment tab, create two variables (make sure you trim the names and values)</li>
</ol>
<pre class="eval"> Name:  LD_LIBRARY_PATH
 Value: .:./plugins:.
 
 Name:  LIBRARY_PATH
 Value: .:./components:.
</pre>
<h5 name="GDB_Timeouts">GDB Timeouts</h5>
<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>
<h3 name="Build_Parallelism">Build Parallelism</h3>
<p>You can use distcc and the MOZ_MAKE_FLAGS build variable to distribute the compilation across a network. This greatly improves the speed of the build. The complete informations are available in the <a class="link-https" href="https://wiki.ubuntu.com/MozillaTeam/Develop/distcc">Mozilla Team Documentation - distcc</a>.</p>
<h3 name="CDT_Issues">CDT Issues</h3>
<p>The CDT has some problems with Mozilla that need to be worked on.</p>
<ul> <li>Code completion and other operations that require a full parse tree are really slow because they parse the compilation unit from scratch every time. This can be fixed -- <a class="external" href="http://dev.eclipse.org/mhonarc/lists/cdt-dev/msg04750.html">there is a plan</a>. But it's quite a lot of work.</li> <li>The parser has bugs. I get a few internal parser errors when parsing the common Mozilla include files that use slightly tricky constructs (e.g., nsCOMPtr). Some of these bugs should be easy to fix, others maybe not. Apparently these bugs are only in the "old" parser which is deprecated and will be completely replaced by the "new" parser, "soon", so it's not really worth working on these bugs.</li> <li>It would be nice if Eclipse could 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've 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.</li> <li>Debugging.</li> <li>Some editing operations get sluggish when you have lots of files open (say, more than 20).</li> <li>The GDB thread terminates unexpectedly and detaches from the Firefox bin. This is caused by the breakpoints currently set. When you restart your Eclipse environment and face such issue. Delete and readd the breakpoints in your list.</li>
</ul>
Revert to this revision