PTP/sync-projects

Basic Information

PTP Synchronized Projects stores files both locally and remotely, and routine creating and editing of files is only done locally. This relieves Eclipse from having to communicate constantly with the remote system. The developer can even work if the network is unavailable. When the network is available, files are synchronized between the local and remote system at various points (if the programmer saves files, attempts to compile, or explicitly requests that files be synchronized). PTP installation instructions are here.

Refer to Synchronized Projects User Guide for basic information.

The July 2011 PTP user meeting user-call recording includes a live demonstration of how to setup and configure a synchronized project. (Note: convert to full-screen viewing via the green square in the lower right corner of the screen to be able to read the contents of the demo screens.)

Known Issues

• Sharing a single remote project between two or more Eclipse instances (at home and at the office, for example) is supported but has an issue if the file filtering is not the same for both Eclipse projects. See bug 410101 for details.
• Sync'ing a very large file (several gigabytes) can cause sync to run indefinitely. The only solution is then to forcibly shutdown Eclipse. Creating good file filters, especially in the new project wizard, will help to avoid this problem.
• The "Build directory" in ('Project' -> 'Properties' -> 'C/C++ Build') does not show the correct build location for remote configurations. Builds should still run in the proper location, though, if set correctly in ('Project' -> 'Properties' -> 'C/C++ Build' -> 'Synchronize').
• There is no wizard to convert existing remote projects to synchronized projects. (See FAQ item below for a solution)
• There are some potential pitfalls when configuring or creating projects
  • For remote configurations, only the "Sync Builder" works, although other options are available ('Project' -> 'Properties' -> 'C/C++ Build' -> 'Tool Chain Editor'). The "Sync Builder" is set as the default for remote configurations
  • Attempting to change multiple configurations does not work correctly.
  • When copying a synchronized project, the new project will not work correctly if a non-default (non-local) file system is specified.

FAQ

When should I create a Remote Project and when should I create a Synchronized Project?

Remote projects exist only on a single remote site. So they are a better choice if you need a simple, quick way to work remotely. Synchronized projects add the capability to use multiple remote sites and synchronize between them. The underlying Git tool makes sync'ing very efficient, leading to less network lag time, especially for large projects. Also, synchronized projects exist and can be built both locally and remotely. Even if you are not interested in compiling locally, this can be handy if the connection is unavailable or slow. For example, you can work on the project locally and then, once the connection becomes available, sync your changes to the remote site.

Other benefits of Sync'd projects include

• Local editing offers improvements over editing remote file (some features are disabled in the C/C++ remote editor) (Example: greying out of inactive code works in local editor)
• You can have multiple remote configurations and switch between building on different remote systems.
• The Fortran indexer can run on a local project but not a remote project

A remote project doesn't need to bring the source files to the local client until you request a file for editing or other operation. A synchronized project brings all the files to the local client upon initial sync then only needs to sync changes later, so editing of already-synced files is faster.

A synchronized project will need more networking initially to do the initial sync, but subsequent requests such as to fetch a file for editing are not needed since the file exists locally.

RDT remote projects requires Java on the remote host. Synchronized projects do not require Java on the remote target.

How do I setup a synchronized project that works with a CVS repository?

1. Create a new CVS project as usual (right-click in 'Project Explorer' -> 'New' -> 'Other...' -> 'CVS' -> 'Projects from CVS")
2. Be sure to select "Check out as a project configured using the New Project Wizard" on the "Check Out As" screen
3. After the CVS wizard ends, the "New Project Wizard" begins.
4. Create an empty Synchronized project
5. Files in the CVS repository are automatically imported on project creation

Alternatively...

1. Check out a project from CVS into a local project as usual (Check out as C or Fortran project if it isn't already)
2. File > New > Other... and under Remote, select "Convert C/C++ or Fortran Project to a Synchronized Project" then select the project and setup (or reuse) a remote connection. Be sure to specify a directory on the remote system for 'Location' where the files will be sync'd to.

How should I use version control with synchronized projects?

Synchronized projects operate independently of version control. However, attempting to synchronize version control information between local and remote repositories can cause problems. Thus, the recommended approach is to isolate version control to either the local side or the remote side, and then use file filtering to prevent transferring version control files.

If you want the version control to be on the remote side, simply create a sync project to the remote directory. In this case, however, you would not be able to use any special support inside Eclipse for specific version control software. For such support, you will need to have local version control. Either way, be sure to add all files related to version control (CVS directory, .git directory, etc.) to the filter from inside the new project wizard so that those files will never be sync'ed.

If you need to run remote commands for version control occasionally, the GUI terminal is ideal for this (right-click on project and select "Show Terminal").

How do I setup synchronization for an existing C/C++ or Fortran project, including ones that use CVS, Git, SVN, etc.?

The conversion wizard, described in the User Guide, should work for all of these cases. Synchronization works independently of the user's version control system.

How do I know if a current project is a synchronized project?

Synchronized projects are marked with an orange double arrow (bottom right corner of the project icon).

I get a merge conflict for a file that changed both locally and remotely. How do I recover from this?

Version 6.0 includes a merge-conflict resolution tool (see documentation), so this procedure should only be needed for prior versions.

1. Shut down eclipse.
2. Synchronize projects "by hand". This means a couple of "rm -rf" or "scp -r" or "make clean" commands on both hosts, as appropriate. The error message about merge conflicts may direct you to the files that need treatment. -- Or you might remove the whole remote project directory, provided the correct version of the files in question are on the local copy.
3. Remove .ptp-sync on >both< hosts.
4. Restart eclipse. The latter is necessary to initiate rebuilding .ptp-sync and redo synchronization.

.ptp-sync is outgrowing rapidly all other directories. Is there any way to reset .ptp-sync ?

Proceed as described above in recovering from a merge conflict. Removing and rebuilding .ptp-sync reduces the size. For PTP 6.0 or later, only steps 3 and 4 should be necessary. Merge conflicts can be resolved inside Eclipse after resetting. Filtering large files, such as binary executables, can reduce the size of this directory.

How do I convert an existing C/C++ or Fortran project to be a synchronized project?

'Project' -> 'New' -> 'Other' -> 'Convert a C/C++ or Fortran Project to a Synchronized Project'

After converting, how do I prevent all local files from being immediately sync'ed to remote? (6.0.0 only)

Future PTP versions will have options for preventing this. (See bug 382504.) Meanwhile, one workaround is to deselect all build configurations in the wizard and create a remote configuration after the conversion. See documentation for how to create new configurations.

When I create a new synchronized project, how do I prevent or minimize the long-running initial sync?

On the last page of the wizard, the "Modify File Filtering..." button can be used to configure file filtering prior to the first sync.

Note that you can use the filtering to sync nothing or to sync only a specific set of files. To do so, first enter a pattern that excludes everything (*) and then add include patterns for specific cases. In fact, entering the * pattern by itself will prevent sync'ing any files initially, and you can then adjust the filter after project creation.

If the remote directory has been synchronized before, you may need to delete the remote .ptp-sync directory before creating a new synchronized project. Otherwise, the initial sync will pull down files in the old PTP Git repository regardless of the filter. The filter will work, though, after the initial sync.

How can I speed up creation of a new Synchronized Project that points to a large remote project?

Since synchronized projects require both a local and a remote copy of files, remote files must be downloaded when the project is created. If the remote project is large, this can take a long time. Only non-filtered files are downloaded, however. So you can speed up the download considerably by modifying the file filtering on the last page of the new project wizard. You can exclude files not needed for development, such as build directories, large binaries, etc. You can always adjust the file filtering after the project is created to add files excluded by mistake.

When I create a new Synchronized Project, why does it sometimes not sync to the remote site? Why does it sometimes build and sometimes not?

This is a known problem still being investigated. If the initial sync does not occur, the next sync will synchronize all of the files. You can either do a manual sync using the context menu, or wait until the next automatic sync, such as on a file save or before a remote build.

After a remote build, why do new remote files sometimes not appear?

This is also a known problem. The next sync will download any new remote files that are not filtered.

Eclipse complains "No such file or directory" when attempting a remote build for a managed project

Managed projects create their build directories. By default they are called "Debug_remote" or "Release_remote." These are created locally and then replicated to the remote host. Please check your replication filter settings and make sure that at least the makefile and make include files in these directories are being transferred to the remote side.

How can I continue using a synchronized project created in PTP 6 after updating to PTP 7?

The workaround for this is to remove and recreate the project in the *local* workspace.

1. Manually synchronize the project. Ensure that all files in the local workspace that you want saved are synchronized to the remote system. 2. Delete the project from the local workspace. 3. Open the new synchronized project wizard. Select the same directory on the remote machine. Select the toolchain for the local and remote configurations. 4. Click finish.

Caveats:

1. Existing synchronized configurations will not be saved, so these will need to be re-created. 2. Existing build configurations will not be saved. If these need to be saved, export them first, then re-import them into the new project.

Change Log

Version 7.0.0

• Reorganization of source packages so that synchronized projects operate independently from CDT. See bug 364191
• Improved file filtering using glob patterns. See documentation and bug 389304
• General synchronized projects are now available without needing to add specific language support (C, C++, or Fortran).
• Scanner discovery for discovering the remote environment (include and library files, compiler and system constants, etc.) is now fully supported. See bug 395477
• Fixed bug 409136: Filter out Remote-only toolchains from new Synchronized Project dialog's toolchain list
• Fixed bug 408496: Environment management should be per-sync configuration not per-project
• Improved context menu. See bug 406655
• Fixed bug 405655: Plus-sign in workspace or project name will not build sync project
• Fixed bug 404411: Synchronized Project Filter window does not resize nicely
• Fixed bug 402350: Sync scanner discovery has corrupt remote paths when using Windows
• Fixed bug 399896: Enhancement: New synchronized project wizard: Select new connection automatically
• Fixed bug 397199: Synchronized projects should allow user to set and change git binary

Version 6.0.4

• Fixed bug 397198: Sync progress reporting needs improvement
• Fixed bug 397197: Git 1.7 or later should use new faster file indexing
• Fixed bug 395732: Values for environment variables are truncated if the equal character is present
• Added sync scanner discovery - not yet fully supported. See bug 395477

Version 6.0.3

• Fixed bug 392606: Patterns for File Filtering should be Editable
• Fixed bug 392603: Problems with Toolchain Selection in New Synchronized Project Wizard
• Fixed bug 389899: Synchronized project: "remote toolchain name" contains spaces

Version 6.0.2

• Fixed bug 385418: Searches in a Synchronized Project include the .ptp-sync directory
• Fixed bug 385541: Extra sync after resource change due to auto build event
• Fixed bug 385549: Inconsistent sync and build behavior when creating or converting to a Synchronized Project
• Fixed bug 385648: Synchronize properties can be saved to wrong build configuration if OK is pressed from a different properties page
• Fixed bug 386244: ChannelExec error during sync after deleting many remote files
• Fixed bug 386267: Unable to import synchronized projects to a different workspace
• Fixed bug 386525: Synchronization very slow when filtering binary files
• Fixed bug 386528: Viewing project properties triggers synchronization
• Fixed bug 388278: Merge view should allow multiple selection when resolving merge conflicts

Version 6.0.1

• Fixed bug 360170: Deleting project fails under NFS
• Fixed bug 382197: New Sync Project wizards do not set Sync Builder
• Fixed bug 382504: Conversion wizard for Synchronized Projects should have file filtering and other options
• Fixed bug 383161: synchronized projects can fail with silent home directory attachment
• Fixed bug 383163: enhancement: provide project directory as suggested remote directory on synch wizard
• Fixed bug 383233: Give option to select the remote version to resolve a merge conflict
• Fixed bug 383243: A non-default location for a synchronized project is not checked for an existing project
• Fixed bug 383662: File filtering does not apply when deleting files
• Fixed bug 383682: NPE on merge conflict for files with no common ancestor
• Fixed bug 383808: Projects created with New Synchronized Fortran Project wizard do not have Fortran nature

Version 6.0.0

• New, improved wizards. See documentation and also bug 380933
• New merge-conflict resolution tool. See documentation and also bug 380897
• Extensive improvements to core synchronization code. See discussion for bug 371507
• Fixed bug 371507: Projects should be relocatable
• Fixed bug 379975: File deleted, both on local and remote, when renamed to a name that only differs by case
• Fixed bug 369778: Remote build broken when sharing synchronized project with git
• Fixed bug 369564: New synchronized project reuses settings from previous project with same name

Version 5.0.6

• Fixed bug 360170: Deleting project fails under NFS
• Fixed bug 372530: Synchronized Projects Filter Dialog - arrangement/grouping

Version 5.0.5

• Add ability to exclude or include files during synchronization. See documentation for details and also bug 369284 and bug 369574
• Fixed bug 367662: Remote sync cannot handle spaces in directory
• Fixed bug 369696: Fix deadlock caused by overuse of sync lock
• Fixed bug 370278: Output from build not printed to console until after build completes
• Fixed bug 370838: Context menu not available in Project Explorer for files and folders

Version 5.0.3

• Fixed bug 358141: Local build configurations cannot be changed to remote build configurations
• Fixed bug 357995: Run configuration browse directory operation does not start in project directory
• Fixed bug 358655: Convert to Sync Project Wizard defaults to home dir
• Disable sync'ing before project deletion. See bug 360170.

Version 5.0.2

• Add sync context menu bug 345673.
• Add wizard to convert local C/C++ or Fortran projects to synchronized projects bug 356813.
• Support files with odd characters bug 354893, with the exception of newline characters bug 355270.
• Add ability to turn off error messages bug 355526.
• Fix bug 356633: Failure to add files to repository if a .gitignore file is present.

Version 5.0.1

• Use separate Git directory (.ptp-sync instead of .git) for sync'ing so that it does not interfere with user's Git repository.
• Sync empty directories.
• Prevent users from modifying the synchronization properties of the Workspace configuration.
• Fix bug 349372: Build fails if empty environment variables are present.
• Support managed project types.
• Add Fortran synchronization wizard.
• Do not sync if only a file's markers have changed (prevents sync'ing during file editing if code analysis is turned on).