Eclipse 3.x Integration

From Seapine Labs

The following article contains screenshots using Eclipse 3.1.2 and Surround SCM 5.0.4.

Also, the Surround SCM client is set up to automatically log in with a designated username and password. This is just to avoid being prompted to enter a Surround SCM username and password at various times.

Contents 1 Installing the Eclipse plug-in 2 Sharing projects 3 Surround SCM tasks 3.1 Adding files 3.2 Getting files 3.3 Checking out files 3.4 Undoing check out 3.5 Checking in files 3.6 Viewing file history 3.7 Viewing file properties 3.8 Comparing file versions 3.9 Replacing file versions 3.10 Renaming files 3.11 Refreshing file status 4 Removing files 5 Disconnecting a project 6 Configuring Surround SCM preferences 7 Troubleshooting Eclipse and Surround SCM integration

[edit] Installing the Eclipse plug-in

1. Start Eclipse.

2. Choose Help > Software Updates > Find and Install to open the plug-in installer.

3. Select Search for new features to install and click Next.

4. Click on the "New Remote Site..." button.

5. Enter a name for the new update site. A meaningful name, like "Seapine Plug-In Site" is recommended.

6. Set the URL to http://downloads.seapine.com/pub/eclipse/surround/, then click OK.

7. Click on Finish on the Install/Update window.

8. Expand the Surround SCM folder, select the sites you want to search, and click Next.

Note: Select the root Surround SCM node to search for all available versions of the plug-in.

9. Select the plug-in version you want to install and click Next.

10. Next, you will be prompted to read the license agreement and accept it to continue.

11. Following is the Install details window. Verify that the plug-in will be installed in the correct directory.

12. The Feature Verification window follows. Click on the "Install" button to proceed with the installation.

13. Click Yes when you are prompted to restart Eclipse. The plug-in is installed and ready to use. Selecting the "Apply Changes" button may cause the plug-in to work properly until Eclipse is restarted.

Note: Next, you need to share the project and set up the integration.

[edit] Sharing projects

Before Surround SCM tasks can be accessed from the Eclipse IDE, the Eclipse project must be associated with Surround SCM.

1. Open the Eclipse project.

2. Select the project and choose Team > Share Project. This can also be selected from the project's context menu (right-click menu).

3. Select Surround SCM.

Note: If Surround SCM is not displayed in the list of version control systems you did not install the plug-in correctly.

4. Click Finish.

The Seapine Surround SCM Login dialog box opens. If the Surround SCM client is set to automatically log in with a sepecified username/password combination, the Surround SCM Login dialog box may not appear.

5. Select the Server you want to connect to.

Click Setup to configure Surround SCM servers.

6. Enter your Username and Password.

If the project has not been added to Surround SCM and Surround SCM is not able to determine an association with a repository, Surround SCM will prompt to set up an association.

NOTE: The association is established throught the .MySCMServerInfo file. Surround SCM will look for this file in the directories in the project path.

7. Select the Branch and Repository you want to point the project to. Figure 10 below illustrates the repository browser window with the "Create Repository" button outlined in red.

8. Click Create Repository to create a new repository for the project. This will assign the directory where the project exists as the working directory for the repository to be created.

NOTE: If an existing repository is selected which already has a working directory assigned, this may cause a conflict if the working directory is a directory different than the directory where the current project is running from.

9. Click OK. The repository browser window should now show the created repository as shown below in figure 12.

10. Once a repository has been associated with the project, click on the OK button.

NOTE: At first, there will be no icons or 'decorations' next to the files to represent their status in Surround SCM. To set this up, please refer to the Configuring Surround SCM preferences section below.

You are now logged in and ready to start using Surround SCM. Integrating Eclipse with Surround SCM 5

[edit] Surround SCM tasks

Note: You can display Surround SCM action messages in Eclipse.

Choose Team > Show Messages. The Surround SCM Messages pane opens. File status information and error messages are displayed in this pane as you work with files.

The Surround SCM actions can be accessed from the context menu of each file (right click menu). Simply right click on any file or package and select "team". Another menu will show up with the Surround SCM tasks available as shown below:

You can perform the following Surround SCM tasks from Eclipse:

[edit] Adding files

NOTE: Sharing an Eclipse project with Surround SCM does not automatically add all the files to Surround SCM. Files can be added individually or as a group by adding the entire package. The only exeption is if the files are in the default package

1. Select the file(s) you want to add to source control.

2. Right-click the file and choose "Team" > "Add Files".

The Add Files dialog box opens. Clicking on the "Advanced" button gives an option to make this action part of a changelist, which is diplayed below.

For a detailed explanation of all of the options in the Advanced Add Files Dialog, please refer to the Surround SCM User Guide.

10. Once all the desired options have been selected and comments have been entered (recommended), click OK.

The files are added to Surround SCM.

[edit] Getting files

Get files when you want to view a file but do not need to make any changes.

1. Select the file(s) you want to get.

2. Right-click the file and choose and choose "Team" > "Get Files".

The Get Options dialog box opens.

Note: You can also select a project and choose Team > Synchronize with Repository to get a copy of all files in the project.

For a detailed explanation of all of the options in the Get Files Dialog, please refer to the Surround SCM User Guide.

3. Click OK to get the file(s).

Surround SCM copies the files into the working directory.

[edit] Checking out files

Check out files when you want to modify them.

1. Select the file(s) you want to check out.

2. Right-click the file and choose Team > Check Out. The Advanced Check Out Options dialog box opens.

For a detailed explanation of all of the options in the Advanced Check Out Options dialog box, please refer to the Surround SCM User Guide.

3. Click OK.

The files are checked out.

[edit] Undoing check out

If you check out and modify a file then decide you do not want to save the changes, you can undo the check out. This discards any changes made to the file and checks it back into the server.

1. Select the file(s).

2. Right-click the file and choose Team > Undo Check Out. The Advanced Undo Check Out Options dialog box opens.

3 Select a File overwrite option.

􀂄 Get original version replaces the local file with the original server version.

􀂄 Get latest version replaces the local file with the latest server version.

􀂄 Leave local file leaves the local file as is.

4. Click OK.

The file is no longer checked out.

[edit] Checking in files

Check in updates the file with changes and makes it available to other users.

1. Select the file(s) you want to check in.

2. Right-click the file and choose Team > Check In.

The Advanced Check in Options dialog box opens.

For a detailed explanation of all of the options in the Advanced Check in Options dialog box, please refer to the Surround SCM User Guide.

3. Click OK.

The files are checked in.

[edit] Viewing file history

File history provides a way to view a source file’s history and work with a historical file version.

1. Select the file.

2. Right-click the file and choose Team > History.

The History dialog box opens. This dialog box includes a summary of historic version information.

For a detailed explanation of all of the options in the History dialog box, please refer to the Surround SCM User Guide.

3. Click Close to close the file history.

Note: You can also select a file and choose Team > Show History in View to open the Surround SCM History pane. You can view historic information and Diff or Get versions of the file.

[edit] Viewing file properties

File properties include general and check out information about the selected file.

1. Select the file.

2. Right-click the file and choose Team > Properties.

The Properties dialog box opens.

3. Click the General tab.

This tab includes read-only information about the file. Depending on your security permissions you may also be able to Expand keywords or select a File type.

4. Click the Check Out tab.

This tab includes read-only check out information about the file.

5. Click OK to close the Properties dialog box.

Note: A Shared tab is also available if the file is shared in Surround SCM.

[edit] Comparing file versions

You can compare a local file with the latest revision in Surround SCM.

1. Right-click the file and choose Team > Compare with > Latest Version.

The compare editor displays any differences between the files.

[edit] Replacing file versions

You can replace a local file with the latest revision from Surround SCM.

1. Right-click the file and choose Team > Replace with > Latest Version.

The local file is replaced with the latest version from Surround SCM.

[edit] Renaming files

1. Select the file you want to rename.

2. Right-click the file and choose Team > Rename. The Rename File dialog box opens. Integrating Eclipse with Surround SCM 13

3. Enter a New Name.

4. Enter any optional Comments.

5. Click OK.

The file is renamed in Surround SCM.

Note: After the file is renamed in Surround SCM you are prompted to rename the file in the project. Click Yes to rename the file and update your project to point to the new file. If you do not rename the project file you cannot work with it unless you add it to Surround SCM or manually rename it.

[edit] Refreshing file status

If you make changes to a file outside of Eclipse you can refresh the file to update its status. For example, if you check out a file from the Surround SCM client it will not be displayed as checked out in Eclipse unless you refresh the file status.

1. Select the file.

2. Right-click the file and choose Team > Refresh File Status.

The file status is refreshed.

[edit] Removing files

You can remove files from Surround SCM control.

1. Select the file you want to remove.

2. Right-click the file and choose Team > Remove. The Advanced Remove Options dialog box opens.

3. Select Destroy to delete the selected files from Surround SCM.

4. Enter any optional Comments.

5. Click OK.

The file is removed.

[edit] Disconnecting a project

You can disconnect, or remove, the Surround SCM association from the Eclipse project. After the project is disconnected, you cannot use Surround SCM with the project unless you share the project again.

1. Right-click the project and choose Team > Disconnect.

The project is disconnected from Surround SCM.

[edit] Configuring Surround SCM preferences

You can configure various functional and display options for the Surround SCM integration.

1. Choose Window > Preferences.

The Preferences dialog box opens.

2. Expand the Team node and select Surround SCM.

3. Select a Save modified files before Surround SCM actions option.

This option determines how modified buffers are handled when a Surround SCM action is initiated.

4. Select a When user attempts to edit a read-only file option.

This option determines what happens when a user tries to edit a local, read-only file in the Eclipse editor.

5. Expand the Surround SCM node and select Label Decorations to set decoration options.

Label decorations display additional information about a file or project by modifying its label or icon.

Note: To enable label decorations for the Surround SCM plug-in choose Window > Preferences > General > Appereance > Label Decorations and check the box next to Surround SCM as illustrated below.

6. Select any Text decoration options.

Text decorations decorate nodes with text based on their status in Surround SCM.

􀂄 Select Decorate files to decorate file nodes based on their existence in Surround SCM.

􀂄 Select Include file check out status to decorate file nodes based on check out status.

􀂄 Select Include file’s local status to decorate file nodes based on local status compared to repository status.

7. Select any Icon decoration options.

Icon decorations decorate nodes with Surround SCM icons based on their status in Surround SCM.

These options require extra processing by Surround SCM and may slow down performance.

􀂄 Select Decorate projects to decorate project nodes based on their sharing status.

􀂄 Select Decorate files to decorate file nodes based on their existence in Surround SCM.

􀂄 Select Include file check out status to decorate file nodes based on check out status.

[edit] Troubleshooting Eclipse and Surround SCM integration

This section can help you troubleshoot more common Eclipse/Surround SCM integration problems.

Surround SCM is not included in the Share Project list Surround SCM is not listed displayed in the Share Project list (Team > Share Project).

􀂄 The Surround SCM plug-in is not installed. For more information see Installing the Eclipse 2.1 plug-in, page 1 or Installing the Eclipse 3.0 plug-in, page 2. The plug-in must be installed for each version of Eclipse you are running.

􀂄 You are running an unsupported version of Eclipse. The Surround SCM plug-in currently supports Eclipse 2.1, 3.0 and 3.1. The integration may not work if you are running another version of Eclipse.

􀂄 The Surround SCM JAR file was not properly installed. Go to <Eclipse install path>/plugins/com.seapine.surroundscm_<version> and make sure the Surround SCM SCCI.JAR file exists in the directory. Re-install the plug-in to resolve this issue. You can also copy the JAR file from your Surround SCM install directory (typically c:\Program Files\Seapine\Surround SCM) to the Eclipse install directory then restart Eclipse.

􀂄 The Surround SCM library file was not properly installed. Find the Surround SCM SCCI.dll file (.so on Unix/Solaris, .jnilib on Mac OS X). Make sure the directory where the .dll file resides is in your PATH.

􀂄 Multiple copies/versions of the Surround SCM library file are installed on your system. The plug-in uses the first library file it finds based on the PATH order. Deleting/uninstalling old copies/versions of the Surround SCM library is the recommended way to resolve this issue.

If you do not want to delete the files edit your PATH and make sure the directory reference to the library you want to use comes first in the PATH. Most Surround SCM menu commands are not enabled Add is the only enabled Surround SCM menu command in Eclipse. Please check the following for possible causes and resolutions.

􀂄 The Eclipse project is not configured correctly. Make sure the project is configured to point to a valid branch/repository. The branch/repository must also exist in the Surround SCM server you are connecting to.

􀂄 Eclipse cannot connect to the Surround SCM server. Make sure the Surround SCM server is running and that your username/password are valid.

􀂄 The local .MySCMServerInfo file is out of sync. Eclipse uses the .MySCMServerInfo file to determine where to look for files in Surround SCM. Go to your project files directory and make sure the .MySCMServerInfo file data points to the correct branch/repository. If it is pointing to an incorrect branch/repository, delete it then refresh the project status to regenerate the .MySCMServerInfo file. Files cannot be added to Surround SCM from Eclipse You cannot add files to Surround SCM from within Eclipse. Please check the following for possible causes and resolutions.

􀂄 The Surround SCM integration is not configured correctly for the Eclipse project. Make sure the project points to a valid branch/repository. Surround SCM may guess where you want to add the files, based on the information in the .MySCMServerInfo file. However, the add cannot be completed if the .MySCMServerInfo file does not exist.

􀂄 Your Eclipse project configuration points to the wrong branch.

This can be an issue if you maintain the Eclipse local project files in Surround SCM then branch the repository that contains the project files. The local files point to the old branch, which is where the files are added. Configure Eclipse to point to the correct branch then add the files to Surround SCM.