Synchronized Projects

Synchronized projects consist of files that are mirrored on the local system as well as on one or more remote systems. Editing occurs locally and each file is synchronized with the currently active remote system when it is changed, created, or deleted. This enables faster interaction with the files and editor, more CDT editor features since the files are local, and continued interaction for editing etc. if the network connection is lost.

Requirements for Synchronized Projects

To host a synchronized project, the remote system must support the Git distributed version control system. Note that this is completely independent of using Git for source code control.

Creating a new Synchronized Project

To create a new Synchronized Project, first select an appropriate wizard:

Select File > New > Other... then in the wizard selection dialog, select Remote > Synchronized C/C++ Project, Synchronized Fortran Project, or Synchronized Project for synchronization only without support for a specific language.

Or, from the context menu (right-mouse) in the Project Explorer of the C/C++ Perspective, select New > Synchronized C/C++ Project, Synchronized Fortran Project, or Synchronized Project for synchronization only without support for a specific language.

Now fill out the New Synchronized Project dialog shown. The dialog for synchronization only will not contain the lower portion for selecting project types and toolchains.

Fill in a name for the project. For Local Directory give the project name and location, most probably the default location within the local workspace directory. Then give a remote location by specifying a connection and remote directory. Next, specify the project type. Finally, select toolchains to be used for remote and local sites. Normally, you will select only one toolchain for each, but it is possible to select additional toolchains. Note that a local toolchain is not required if you do not need to build locally.

File filtering specifies which files will be synchronized between the local machine and the remote target. The default can be altered for this new project via the Modify File Filtering... button. By default, eclipse-related files such as .project are not synchronized between the local and the remote system. Binary files are. See File Filtering for more information. See Sync Preferences for information on how to modify the default behavior for subsequent new synchronized projects.

At this point you may select Finish to complete project setup with defaults for the remainder of the options.

Alternatively, you may select Next to scroll through the remaining pages, which differ based on the selected project types and toolchains. This includes the configuration page, which will list a separate build configuration for each toolchain selected earlier.

From here, you can configure build properties. (This can also be done after the project is created.) Note that if you select the same toolchain for both local and remote, only one configuration is shown. During project creation, this configuration will be duplicated, creating one for local and another for remote.

If you then select Next > instead of Finish, the Default Build Configurations page appears. See Working with a Synchronized Project for more information on sync configs and build configs.


Select Finish to end the New Project Wizard.


Creating a remote connection

On the first wizard page, the New... button can be used to create a new remote connection. Fill in host name, user, and password (or other authentication information). Select Finish. The connection is not tested until you return to the previous dialog and select the Browse... button or some other communication is required.

Note: To edit connection information after a connection has been created, e.g. to change user name or password, see Editing Remote Connections in Remote Tools.

Working with a Synchronized Project

In Eclipse Kepler (PTP 7.0), the settings for synchronization and for building have been separated. For the former, sync configurations are used and are available in all synchronized projects. These are used mainly to specify where (machine and directory) local files should be synchronized. For building, build configurations are used and are only available for synchronized C, C++, or Fortran projects. They are used to configure build parameters, such as the compiler and compiler options. These two configuration types operate mostly independently, and sync'ing or building always uses the current active sync configuration or active build configuration, respectively.

The only dependence is that builds occur, by default, at the location specified by the active sync configuration. Also, you can specify a default build configuration for each sync configuration. When switching to a different sync configuration, its default build configuration is automatically selected. This is only for convenience, so that two settings do not need to be changed when switching to a different remote. You can also change the build configuration independently of the sync configuration. It is common to have multiple types of builds, say a "debug" and a "release" build, for the same source location or even to use the same build configuration for multiple remote locations (sync configurations).

The starting sync configuration will be for the remote system with its default build configuration, if selected in the wizard. Thus, for the most common case (a single remote site to be modified and built), a synchronized project works out-of-the-box. If the remote location does not exist, it is created. Otherwise, the files in that directory will be synchronized to the local workspace. Edit the files as you would any local project. Each time you save a file, it will be synchronized with the remote system. If you create or delete files, the remote system will be updated appropriately. Note that a local sync config is always created for convenience, even if no local tool chain was selected. It provides a simple way to disable all remote operations and work locally without changing other sync settings.

To build the project (assuming you have already created a makefile), make sure the project is selected in the Project Explorer view, then click on the build icon (the icon that looks like a hammer). The Console view shows the results of the build.

For more examples of creating and building a simple new Synchronized project, see Introduction to Creating MPI Projects.

For more information on build configurations, sync configurations, etc. see Sync Configurations on the Building Synchronized Projects page.

Changing sync behavior with the Sync Context Menu

The sync context menu lets you view or alter several properties related to the sync behavior. To access the sync context menu, right-click on the project in the Project Explorer view and move down to the Synchronize sub-menu.

From this menu, you can force a synchronization immediately for the active sync configuration, Set the active sync configuration, Manage configurations (sync configurations and their associated build configurations), force a sync of all the sync configs, etc. Auto-sync (Global) and Auto-sync Settings allow you to alter the behavior of automatic sync'ing for all projects or per project.

Prior to a build, files are always updated with a forced sync of only the active configuration, regardless of any settings. This ensures that the build is based on the latest revisions. Another sync may occur after the build to update files, since the build may alter the remote files during compilation. (This sync, however, does respect the user's settings.) See "File Filtering: Changing which files are synchronized" for information on the "Filter..." option.

File Filtering: Changing which files are synchronized

By default, all files are usually synchronized.

But some files do not need to be synchronized between local and remote locations. For example, binaries may not be of use on the local machine (and may be large and slow to replicate), but source files usually are since they are usually edited from the local Eclipse workbench but used to build on the remote target system.

From the "Filter..." option of the sync context menu,

you can change which files are synchronized for the current project. You can also change the default settings for future projects on the Synchronized Projects preference page. By default, files and directories specifically used by Eclipse are excluded from synchronization. (Note that these files, such as .project and .project etc. are normally not visible.)

Sync filtering information is accessible in three places:

  1. The Configure Synchronize Project Filters dialog (sync filter dialog) for existing projects, available from the sync context menu shown above, is shown below. It shows settings and what it does to files in the currently selected existing project
  2. The File Filters popup dialog from the new synchronized project dialog (from the Modify File Filtering... button) allows setting sync filter settings as a project is created, and
  3. The Sync Filters Preference page sets defaults that will be used in new projects.

Parts of the Configure Synchronize Project Filters dialog for an existing project:

Each part of the dialog updates automatically if the other part is changed, so that they are always in agreement. This allows you to see immediately the effect of adding a new pattern. By default, remote files are not shown. Showing remote files may lead to a slower response time while updating views. Check Show remote files if you wish to view them. An error message is shown if the remote system is disconnected.

To enter a new pattern, select the Add... button. The Add Pattern dialog appears.

In the Pattern: field, enter a pattern which uses Git syntax (gitignore)

Select the radio button beneath the Pattern: field to indicate whether the pattern should be included or excluded in the synchronization. Default is excluded.

Patterns are applied in the order given in the patterns area of the Configure Synchronize Project Filters dialog. New patterns are placed at the bottom (highest precedence). So a file will be excluded or included based on the first matching pattern, or included if no pattern matches. Use the "Move Up" and "Move Down" buttons to change a pattern's priority. If a new pattern is identical to an old pattern, the old pattern is removed. Note that it doesn't matter whether the old pattern was an exclude or include pattern, since the new pattern supersedes it.

For example, to exclude *.o files from synchronization (e.g. they are built on the remote system but you do not want them copied back to the local directory), Select the Add... button in the patterns area of the Configure Synchronize Project Filters dialog.

Type *.o in the pattern field and make sure that Exclude is selected for the Pattern Type.

Then select the OK button. The new filter will appear in the patterns area of the Configure Synchronize Project Filters dialog, and the *.o files are no longer included in the synchronization.

You can move the priority up or down, edit the pattern, etc. with the buttons.

Hit OK to save any changes you have made to the sync filtering.

Converting a project to a Synchronized Project

The conversion wizard allows you to convert any project type to a synchronized project. Currently only local projects can be converted. To convert a project, right-click in the Project Explorer view and select New > Other... In the wizard selection dialog, select Remote > Convert to Synchronized Project and select Next>.

From this dialog, you can select a project to convert.

Select a local project to convert it to a synchronized project. Select a connection (or create a new connection.)

Select Next> and in the next dialog, select the default Build Configurations for each Sync Configuration (only for C, C++, or Fortran projects).

Select Finish and the project is synchronized (copied) to the remote system specified by the connection.

Resolving merge conflicts

A "merge conflict" can occur, in general, when merging two different versions of a file into a single version. There may be disagreement, for various reasons, on what the final version should be. For synchronized projects, merge conflicts do not occur during normal use, because the underlying system knows that local file changes are updates to older remote versions, or vice versa. Merge conflicts may occur, however, if files are changed both locally and remotely without an intervening sync, because the next sync may not know how to merge the two versions. (It is a good idea to sync after making remote changes before resuming work in Eclipse.) When a conflict is detected, the following dialog appears:

You can open the merge conflict view from this dialog or from Window > Show View > Other.. and then Remote Development > Synchronized Merge View. The Synchronized Merge View (probably at the bottom of the workbench window) shows a list of conflicting files. (You may need to select the project in Project Explorer if the viewer is empty.) Double-click a file in the Synchronized Merge View to bring up a "compare editor" where differences can be viewed and conflicts resolved. In this editor, the left pane shows the local file, which has been marked up to show conflicts, and the right pane shows the remote file. The "ancestor" file optionally appears above these two panes and can be toggled on or off using the editor's leftmost icon. The ancestor is the last known version of the file from which both local and remote are derived. Also note that right-clicking the file in the viewer brings up a context menu from which certain options can be selected (discussed below).

In the compare editor, editing the left pane edits the local version of the file. The compare editor is only for convenience. You can also edit the file from the normal Eclipse text editor. When finished editing, be sure to save the file and then select Mark as resolved from the context menu in the Synchronized Merge View. This version will be copied to the remote site on the next sync. Do the same for each conflicted file. Sync'ing is blocked until all conflicts have been resolved. Instead, the merge-conflict dialog will appear. (Click the checkbox in the merge-conflict dialog to disable it until the merge is resolved.) It is a good idea to sync manually after resolving the merge to push the edits to the remote system. To sync manually, select the project in the Project Explorer view and click right-mouse, Synchronize > Sync Active Now.

After a merge conflict, the local file has markers and annotation added to show the differing content on the local and remote sites. This is useful for editing the file by itself, but not so much for using the compare editor. Select Reset to version before merge in the context menu of the Synchronized Merge View to revert the local file to its prior version. Now the compare editor will show clearly the differences between local and remote. Sometimes you may simply want the remote version of the file. Selecting Resolve as remote makes the local file identical to the remote version and then marks it as resolved.

Discovering the remote environment (remote includes and code analysis)


Modern software projects almost always depend on external code, macros, and variables, which are introduced into source code through include directives and various compiler commands and settings. We refer to all of these external elements as the project's "environment." Detecting this environment is a difficult problem but essential in order for Eclipse to provide useful code assistance (bug highlighting, code navigation, etc.) It is difficult because this environment is partially built into the compiler and partially "discovered" by the compiler while building. CDT has a long history of developing scanner discovery to solve this problem and recently unveiled a redesign of the discovery mechanism. Synchronized projects extends this new redesign so that discovery can reflect the environment of the current remote machine (as specified by the active build configuration). At the moment, only the GCC compiler is supported. Note that CDT still makes available the old method of scanner discovery, but it has not been extended to work with synchronized projects.

The elements discovered by scanner discovery are used by the CDT indexer and the CDT Codan (CODe ANalysis) tool. The former is a potentially long-running task that gathers information about all of the source code components (variables, functions, classes, etc.) Codan then uses this information to analyze and potentially mark up source files with various bug reports and warnings. Each of these three components (discovery, indexing, and Codan) run independently and at different times. In addition, the build process may produce markers for compiler errors in the Problems view. Codan uses an icon that resembles a bug, which distinguishes it from the more traditional icons used by the build system. (Due to the complexity of analyzing C++, it frequently occurs that programs will compile while still showing Codan markings. This can be due to problems in discovery, indexing, or code analysis.)


Note: also related: Include files for Synchronized Projects

By default, a synchronized project uses the normal CDT discovery mechanism, which reads the local environment. To configure the new discovery elements, follow these instructions after creating a new synchronized project. Go to Project > Properties > C/C++ General > Preprocessor Include Paths, Macros etc. Make sure the remote configuration is selected at the top of the dialog. Under the Providers tab, deselect all CDT providers, except for "CDT User Setting Entries" if you would like to enter your own paths. Next, select the two Sync providers, "Sync GCC Build Output Parser" and "Sync GCC Builtin Compiler Settings." The latter provider runs a specially-crafted compiler command to get compiler-specific settings. It will run immediately after "OK" is selected. The former provider will execute simultaneously with builds. It intercepts the build output and attempts to find environment information. Thus, a build must be run before this provider is useful.

Now, make sure that indexing is enabled and invoke a remote build. In order for the build output parser to be useful, builds must produce verbose output. The method for setting up such a build varies per project, but see the Mozilla Project CDT setup page for a good example. Repeat these steps for each remote build configuration. For local configurations, both the standard CDT or new Sync providers should work. If you would like the environment to update automatically when build configurations are switched, go to Project > Properties > C/C++ General > Indexer and select "Use active build configuration" for "Build configuration for the indexer." The downside of this is that the indexer will run each time you switch configurations.


The list of discovered paths and macros can be found under the Entries tab on the above page. Note that the connection name is prepended for remote includes (UNC notation). When adding your own entries, you can use this same notation to specify a path on a remote machine or a local path by leaving off the connection name. (Thus, remote configurations can use local paths and vice versa.)

By default, the build output parser discovers entries per file. This can be changed under the Providers tab (see above figure). If discovery is per file, though, the list of includes and macros will be empty if accessed from the project menu or by right-clicking on the project or a folder and selecting Properties. Instead, right-click on an individual file and select Properties to see the entries for that particular file.

Sync Preferences

The preferences page for Synchronized projects includes setting defaults for sync filtering.

See also PTP Preferences.



  • The indexing of source files can take a long time. You may want to cancel the process or disable indexing altogether until the above setup is complete (Project > Properties > C/C++ General > Indexer)
  • The Indexer page also has some useful settings for fine-tuning the indexer.
  • To re-index, right-click on the project and select Indexer > Rebuild
  • In the Providers tab (not the Entries tab), use the Clear Entries button to erase entries for a specific provider. Doing this is often necessary after creating a new configuration for a different remote. The entries for the copied configuration are copied to the new configuration.
  • The build output parser operates on build output lines containing the name of the compiler executable. Under the provider tab, change the "Compiler command pattern" (see above figure) if it does not match your executable name. For example, if you are using MPI your executable may be "mpicc," "mpic++," or "mpiCC." Be careful to mimic the regular expression format. For example, to add "mpic++" append: |(mpic\+\+) to the pattern.
  • If switching configurations does not alter the environment, double-check the Indexer "Build configuration for the indexer" setting. For some reason, it will sometimes reset to use a fixed configuration, such as when Eclipse is restarted.
  • See also Synchronized Projects usage info on the PTP Wiki page for more information on synchronized projects.




    See Local Vs. Remote Projects for more information on the different kinds of local and remote projects.


    Back to Top | Back to Table of Contents