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.

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 or Synchronized Fortran Project



Or, from the context menu (right-mouse) in the Project Explorer, select New > Synchronized C/C++ Project or Synchronized Fortran Project



Now fill out the dialog shown.



As for any Eclipse project, give the project name and location, which must be a local directory for a Synchronized Project. 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.

Select Next to scroll through the remaining pages, which differ based on the selected project types and toolchains. At some point, you should see 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.

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 will be tested at this point.


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

The starting configuration will be for one of the remote toolchains. 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.

By default, a synchronized project is configured to build on the same remote host as for synchronization. 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).

Synchronization and building are done between the local workspace and the active configuration. You can change the active configuration by using the "sundial" icon next to the build icon, or build and switch simultaneously using the arrow next to the build icon. Local configurations have sync disabled initially and build in the Eclipse workspace.

You can create configurations to synchronize and build on other remote systems from the C/C++ Build > Synchronize project properties. To bring up the Synchronize project properties, in the Project Explorer view, select the project and choose Properties from the context menu (right click). You can also use these property pages to modify configurations in general. See the CDT documentation for more details.

Changing sync behavior with the Sync Context Menu

The sync context menu lets you alter the sync behavior and can be accessed with a right click on a sync project. From this menu, you can turn off automatic sync'ing (sync after saving files and other resource changes) so that syncs only occur on request. This setting is applied to all projects in the workspace. The "Project Auto-Sync Settings" submenu allows you to alter the behavior of automatic sync'ing per project. The next two selections allow you to force an immediate sync of the current project. A "sync all" syncs all configurations of a project. Note that this can be quite slow if your project has several configurations. 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 "Changing which files are synchronized" for information on the "Filter..." option.

Changing which files are synchronized

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 Project" preference page. For files and folders, "Exclude Selection" and "Include Selection" shortcut options are also available from the context menu. By default, files and directories specifically used by Eclipse are excluded. (Note that these files, such as .project etc. are normally not visible.) The "File View" always indicates the currently excluded and included directories and files, while the "Pattern View" always shows the current exclude and include patterns. (The file view is not shown on the preference page.) Each view updates automatically if the other view 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. An error message is printed if the remote is disconnected.

You can deselect or select directories or files in the File View, which will add the corresponding exclude or include pattern to the pattern view. These are "path" patterns, meaning that directories or files in the specified path are excluded or included. Underneath the Pattern View, you can manually enter a path (Enter Path:). You can also enter a regular expression ("regex") that is compared to the project-relative path. The regular expression syntax is that of the Java programming language. An error message is printed if the regular expression is not valid. Finally, you can select "special" patterns from the "Select pattern" drop-down. Currently the only special pattern is one for matching binary files.

Patterns are applied in the order given in the Pattern View, and new patterns are always placed at the top (highest priority). So a file will be excluded or included based on the first matching pattern, or included if no pattern matches. Use the "Up" and "Down" buttons to change a pattern's priority. If a new pattern is identical to an old pattern and has the same type, 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.

Converting a project to a Synchronized Project

The conversion wizard allows you to convert current C/C++ or Fortran projects to synchronized projects. Currently only local projects can be converted. To convert a project right-click in the workspace and select New > Other... In the wizard selection dialog, select Remote > Convert C/C++ or Fortran Project to a Synchronized Project > Next. From this dialog, you can select a project to convert and configure a remote site. See Creating a remote connection for details on creating new connections. The selected configurations are duplicated to create a local version and a remote version. Unselected configurations remain as local configurations only. After creating the project, you may want to change the toolchain for the remote configurations. You can do this from Project > Properties > C/C++ Build > Tool Chain Editor. After selecting a toolchain, you must change the current builder back to the "Sync Builder" in order for builds to occur remotely.

Note that in order to have a project appear in the list of projects to convert to synchronized, the project must already be a C/C++ or Fortran project.

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. This view 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 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. 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.

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

Introduction

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 tasks that gathers information about all of the source code components (variables, functions, classes, etc.) Codan then uses this information to analyze and potentially markup 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 markings for compiler errors. 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.)

Setup

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.



Results

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 provider's 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.

Tips

  • 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, doublecheck 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 information available after the PTP 6.0 release.

     

     

     

    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