Eclipse Plug-in Guide

Overview

This guide provides information and instructions for installing and using the Sablime Eclipse* plug-in. This plug-in supplies an interface between Sablime and the Eclipse IDE framework.

Installation

The Sablime Eclipse Plug-in is installed using the Eclipse Software Update facility. The process may vary a bit from Eclipse release to Eclipse release. Basic directions are given for several recent versions.

  1. Start Eclipse, and on the Help menu, select...
    Version Selection
    3.[3 or earlier] Software Updates > Find and Install...
    then select Search for new features to install...
    and click Next
    3.4 Software Updates..., then Available Software
    3.5 and later Install New Software...
  2. Depending on your exact version, select New Remote Site... or Add Site... or Add....
  3. Enter the name “Sablime Eclipse Plug-in” (skip this on 3.4), and the URL http://sablime.alcatel-lucent.com/eclipseplugin/update/ and click OK.
  4. Check the box for “Sablime” (and click Next, depending on Eclipse version).
  5. Check the box for “Sablime Team Provider version number” and click Next or Install..., depending on Eclipse version.
  6. Accept the license, and click Next.
  7. Click Finish. Note: the plug-in takes about 230KB disk space to install.
  8. Click Install to finish the installation.
  9. Click Yes to restart Eclipse.

Once the installation is successful, Sablime operations (Add to Sablime, Check Out, Reserve, etc.) will appear on the Team sub-menu when you right-click in Eclipse's “Project Explorer” or “Editor” views.

Return to: Top of PageInstallation

Usage

Note The Sablime Eclipse plug-in allows users to perform actions such as renaming and deleting files. In the traditional Sablime environment and in Web Sablime, these actions are reserved for the Source Administrator.
If you do not want Eclipse users to be allowed to do these actions, you can change the $OPEN_PERM setting in your Web Sablime configuration file at $sabLCB/web/wsab/wsab.conf.

Users must be enabled for Web Sablime before using the Eclipse plug-in. The user should log into the Web Sablime URL at least once (to establish a default preferences file) before using the plug-in.

Share an Existing Eclipse Project with Sablime

  1. Right-click on the project and select Team > Share Project...
  2. Select Sablime from the Repository Type list
  3. Enter your Web Sablime server URL (e.g., http://mymachine.mydomain.com:6060), user-name and password; click Next.
  4. Select the Sablime product and generic from the drop-down lists.
  5. Select an MR from the drop-down list of MRs assigned to you, or create a new MR with the New MR button. This MR becomes the default MR for the project and is used to addsrc files from the project into Sablime.
    If the Automatically add current project files check box is left unchecked, the MR is optional.
  6. Select the parent directory for the project from the drop-down list of existing directories in Sablime. If the desired parent directory does not currently exist in Sablime, it must be created on the server using adddirs.
  7. Enter the name of the (new) sub-directory that the project will be stored into. This directory should not already exist (see next note). The default name is the name of the project in Eclipse.

    The plug-in will not share a project into an already existing sub-directory unless Automatically add current project files check box is unchecked.
    This feature can be used to re-attach an Eclipse project that has been accidentally deconfigured.

    If the Automatically add current project files check box is checked, all files in the project - except those matching patterns in Window > Preferences > Team > Ignored Resources - will be added.

  8. Click Next or Finish

    Next takes you to a page for establishing various optional settings for Sablime commands used in Eclipse.

  9. Click Finish to start the share operation.

Return to: Top of PageUsageShare...

Import an Eclipse project (stored in Sablime) into Eclipse Client

  1. From the File menu, select Import ....
  2. Pick Project from Sablime (in the Sablime folder) as the import source, and click Next.
  3. Enter your Web Sablime server URL (e.g., http://mymachine.mydomain.com:6060); user name and password; and click Next.
  4. Select the Sablime product and generic from the drop-down lists.
  5. Optionally, select an MR from the drop-down list of MRs assigned to you, or create a new MR with New MR. This MR becomes the default MR for the project.
  6. For Get Files From:, select whether you would like to choose from a list of directories in the generic that appear to be Eclipse projects (i.e. they have a .project file) or from all directories in the generic. Click Next.
  7. Select a directory to import. Shift-click to select more than one.
  8. Enter the name of the project to create. The default is the last component of the directory name. If multiple directories are selected, the default name is used automatically.
  9. Select a local directory for the project. The default is a directory with the same name as the project, in the current Eclipse workspace.

    If you uncheck Use default value, you may create the project in any directory outside of the workspace (use Browse to create a new directory).

    If the Download File Content check box is checked, all files in the Sablime directory will be downloaded into the new project. The content will come from the latest version on the file’s “mr” or “ofc” branch (i.e. latest changes, or all changes by approved MRs). Default is “mr”.
    If Download File Content is unchecked, the project will show a view of the Sablime directory with all the files marked as “[Remote]”. The files may be made local by using the Check Out action or the Replace With... actions. This feature is useful for downloading only some files of a project or directory containing a large number of files.
    Note that Eclipse functions or plug-ins will not work properly with remote files. In particular, the JDT complains in the log file about not being able to read the .classpath file.
    The .project file is always downloaded if it exists - regardless of the Download File Content setting.

  10. Click Next or Finish.

    Nexttakes you to a page for establishing various optional settings for the relevant Sablime commands.

  11. Click Finish to start the import operation.

Return to: Top of PageUsageImport...

Stop sharing an Eclipse project with Sablime

  1. In the Window > Show View > Project Explorer view, right-click on the project name and select Team > Deconfigure.

Return to: Top of PageUsage

In the Window > Show View > Project Explorer view, right-click on a file name, a folder name, or on a project name and select Team. The Team menu is also available by right-clicking anywhere in the editor window while you are editing a file. The currently supported Sablime actions are:

Some selections on the menu may be unavailable, depending on the current status of the item.

Refresh Status
File status is not periodically updated, so this command can be used to manually refresh the status. The project or folder form of this action discovers files that have been added or deleted in Sablime outside the current Eclipse instance. The new file will show up with the “[Remote]” tag; you must use either Check Out or Replace With... to retrieve the file’s contents. Files deleted in Sablime are not deleted in Eclipse (unless they were remote to begin with).
Add to Sablime
Addsrcone or more locally created files to Sablime.
Check Out
Edget one or more files.
Check In
Edput one or more files.
Undo Check Out
Unedget one or more files
Reserve or Unreserve
Reserve or unreserve one or more existing checkouts.
Merge or Mark as Merged
Resolve check-in conflicts of unreserved checkouts (merge).

The Usage Guide links on the Sablime command names above describe the Web Sablime usage of the indicated command, for reference. The Team selections actually trigger streamlined Eclipse-specific versions of the Sablime commands. Command options can be selected on the Sablime Properties tab of the action pop-up.

You can also right-click on a file, folder, or project and select one of these Sablime-related actions from the menu:

Compare With > Latest from MR branch
Bring up a comparison window showing the difference between the version of the file in the Eclipse client and the version most recently stored into Sablime.
Compare With > Latest from Official branch
Bring up a comparison window showing the difference between the version of the file in the Eclipse client and the Sablime version having content from approved MRs only.
Replace With > Latest from MR branch
Replace the local version with the version most recently stored into Sablime.
Replace With > Latest from Official branch
Replace the local version with the Sablime version having content from approved MRs only.

A selection on a folder or the project applies the action to all eligible files and subfolders (recursively) under the folder or project. Multiple files may also be selected for an action by using control-click.

Actions that operate on multiple files bring up a confirmation dialog showing the file list so that files can be de-selected as necessary.

Most actions bring up a confirmation box in which options can be configured (see action notes below).

Return to: Top of PageUsageMenu Actions...

Notes on Individual Sablime Actions

Adding files to Sablime
A different MR may be selected from the Sablime Properties tab of the confirmation dialog. Addsrc options (e.g., Version Control Tool) may be set from the Sablime Options tab.
Checking files out
A different MR may be selected from the Sablime Properties tab of the confirmation dialog. Edget options (e.g., Reserved Checkout) may be set from the Sablime Options tab.
Checking files in
A check in comment may be entered using the Comments tab of the confirmation dialog. Edput options (e.g., File-Level Dependency) may be set from the Sablime Options tab.
Merging files
If conflicts are detected on a check in of a file (because other changes have been edput to the file by another MR outside of this Eclipse instance), then the file requires merging (indicated by the “(MergeNeeded)” tag in the file’s label).

The workbench will show a 3-way comparison between the last common ancestor (top pane but initially hidden); the latest version in Sablime (right pane); and the current local version (left pane). If the comparison view is dismissed, it can be brought back by selecting Team > Merge...

You can make changes to the local version (in the comparison editor) to resolve the conflict. When the conflict is resolved, right-click on the file and select Team > Mark as Merged. Right-click on the file again and select Team > Check in to complete the check in.

Return to: Top of PageUsageNotes on...

Item Icons when Under Sablime Control

Project
The project icon will have a database symbol ((Image shows small database icon).) overlaid on the lower right, and [sablime @ Web Sablime Server URL (user)] appended to its text label.
Folder
The folder icon will have a database symbol ((Image shows small database icon).) overlaid on the lower right.
File, Checked In
The file icon will have a database symbol ((Image shows small database icon).) overlaid on the lower right.
File, Checked Out (by this Eclipse client)
The file icon will have a checked-out symbol ((Image shows small check mark icon).) overlaid on the lower right, and [mr], or [mr(reserved)] appended to its text label (where mr is the MR used for the check out.
File, Checked Out (elsewhere)
The file icon will not have a check mark symbol, but [OtherCheckouts] or [OtherCheckouts (reserved)] will be appended to its text label.
This information will only be current as of the most recent Team > Refresh Status.
File, Remote
If a file’s text label is tagged [Remote], the file has no local content and cannot be viewed until the content is retrieved from Sablime using either Team > Check Out or one of the Team > Replace With... actions.

Return to: Top of PageUsageItem Icons...

Property Pages

There are Sablime-specific property pages for files, folders and projects. Right-click on the item in the Window > Show View > Project Explorer view and select Properties, then Sablime.

The default MR for a project can be set on the Sablime Property tab of the project’s properties.

The Web Sablime server URL, username, and password may be changed from the Web Sablime Information tab.

Sablime plug-in defaults can be configured through the property dialog at Window > Preferences, then Team, then Sablime.

Return to: Top of PageUsageProperty Pages

Technical Notes

What gets added when an Eclipse project is added to Sablime

All the files in the project are addsrced, excluding those that match some pattern in the list at Window > Preferences > Team > Ignored Resources.

Various plug-ins (e.g., the Java* IDE, the C++ IDE, etc) have files that aren’t source files and shouldn’t be added to Sablime; unfortunately not all of these files are on the default ignore list. Users should add these patterns to the ignore list:

  • *.class — (From the Java IDE - no idea why this isn’t in the default ignore list)
  • build.xml — (generated build script)

Other files may be added to the ignore list at your discretion.

Return to: Top of PageUsageTechnical Notes

Consequences of adding project metadata files such as .project and .classpath to Sablime

We’re confident that adding these files to Sablime is the right way to go as they contain important information about the project (dependencies, build paths, etc). Users should be aware, though, that when the project is saved, the project properties are saved too, so it’s important to ensure that those property values are as developer independent as possible. In the case of the Java IDE, that means that Project > Properties > Java Build Path shouldn’t contain absolute paths.

Return to: Top of PageUsageTechnical Notes

Consequences of metadata files being read-only

Most metafiles are edited indirectly from a properties page or special editor. It is their responsibility to make the call that triggers Sablime to check out a file if necessary. Unfortunately, sometimes the editor doesn’t do this and the operation fails because the underlying file isn’t writable. This seems to be less of a problem in recent Eclipse versions. The workaround is to check out the file manually before invoking the editor.

.project and .classpath files are a bit of a special case since they are somewhat hidden and an inexperienced user may not realize the connection between them and the Project > Properties page. One needs to use the Window > Show View > Navigator view to see them.

Return to: Top of PageUsageTechnical Notes

Making local changes to metadata files

If you want to make a change to a metadata file without checking it out (e.g., make an experimental change to .classpath), you can make the file writeable (either in the underlying filesystem or via the file’s Properties in Eclipse). Caution should be used, since the experimental changes could be lost when a normal check-out/check-in happens.

Return to: Top of PageUsageTechnical Notes

Known Problems and Limitations

Return to: Top of PageKnown Problems

Plug-in Updates

If you are notified that there is an update available for the Sablime Eclipse plug-in, you can install it as follows:

Start Eclipse, and on the Help menu, select...

Version Selection
3.[3 or earlier] Software Updates > Find and Install...
then select Search for updates of currently installed features... and click Finish;
3.4 Software Updates... Installed Software
select the Sablime Eclipse Plug-in, and click Update...
3.5 and later Check for updates...

Eclipse will then search for available updates. Select the updated Sablime Eclipse Plug-in and follow the prompts to complete the update.

Return to: Top of PagePlug-in Updates

Uninstall

If you want to uninstall the Sablime Eclipse Plug-in:

Start Eclipse, and on the Help menu, select...

Version Process
3.[3 or earlier] Manage Configuration - Locate and select the Sablime Plug-in (in the left-hand frame)
Select Disable in the right-hand frame and then OK
Let Eclipse restart, then return to the Manage Configuration screen
Click the Show Disabled Features menu button (3rd from left).
Locate and select the Sablime Plug-in in the left frame, and select Uninstall in the right.
3.4 Software Updates..., then Installed Software
select the Sablime Eclipse Plug-in, and click Uninstall...
3.5 and later About..., then click Installation Details
select the Sablime Eclipse Plug-in, and click Uninstall...

Return to: Top of PageUninstall


* Eclipse is a trademark of Eclipse Foundation, Inc.
Java and Solaris are trademarks or registered trademarks of Oracle and/or its affiliates in the United States and other countries.
UNIX is a registered trademark of The Open Group.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.
Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries.

Sablime is a registered trademark of Alcatel-Lucent Inc.
Contents copyright © 2010-2015 Alcatel-Lucent. Permission to photocopy in support of a licensed installation of Sablime is hereby granted.