Thursday, 7 May 2015

Symlink issues for Eclipse users on Windows

The Dart team currently recommend that the Eclipse plugin not be used on Windows. This post explains the reason for this and provides workarounds to allow Eclipse to be used successfully on Windows.


Whenever Pub is used to retrieve packages from Dart repositories, the actual files are stored in a system-wide cache (located in the user's roaming profile) and made accessible to individual projects using a symbolic link (or 'symlink') to the cached package directory. Creating and deleting these symlinks provides a simple way of adding and removing packages without having to copy or delete the package contents. At the Windows file-system level this works well and managing the symlinks using Windows Explorer works as expected.

Eclipse provides several file management functions via the Project Explorer window including the option to delete project resources. Unfortunately, the Windows implementation of this is such that deleting a symlink to a directory also deletes the files stored in the directory itself, so that removing a package from a project also removes it from the Pub cache. Even worse, the package is not deleted entirely, only its source files are removed; the package directory structure is retained making it harder to simply reinstall the package using the Pub get command.

At the time of writing the Dart team is working on a solution to replace the use of symlinks in the Dart package system and when this is released the deletion-problem should no longer be a problem. Until then do not use the Project Explorer 'delete' action to remove packages or any directories containing packages (including the project folder itself).


So if you are using Eclipse to develop Dart applications there are two scenarios to be wary of. The first is deleting directories from the project. Just don't do it; use Windows Explorer instead and delete them directly from the file-system and use F5 in Eclipse to update the project view.

The second is deleting entire projects. You will need to delete the project from within Eclipse to remove it from the Workspace but be sure to leave the Delete project contents on disk option unchecked. This will remove the project from the workspace but leave the files intact. Again, use Windows Explorer to delete the actual files and any symlinked directories it might contain.

If you do accidentally delete a cached package the pub command can be used to retrieve the deleted files after a little bit of clean-up. Use Windows Explorer to remove the empty package directory from the pub cache and retrieve a fresh copy using pub get. Alternatively, if you have deleted many packages, run pub cache repair to rebuild the cache. Finally, the nuclear option would be to just delete the cache in its entirety and build it from scratch using pub get on each of your projects.

In summary, the Eclipse bug is a pain but should eventually be a thing of the past allowing Eclipse to be used as a convenient (and free) alternative to the official WebStorm option. If you do fall foul of it just remember that a little 'pub-fu' can restore any packages you might accidentally delete.