Dec2005: Released with v6.u1u1. Other than the title, the document is unchanged relative to v6.1.

Transcription

1 Sablime v6.1 Update 1 Visual Studio* Plug-in Guide April 2005 Dec2005: Released with v6.u1u1. Other than the title, the document is unchanged relative to v6.1. What this Guide Covers This guide provides information about and instructions for installing and using the Sablime Visual Studio Plug-in with either Sablime v6.1 or Sablime for Windows* sfw1.1. Introduction The Sablime Visual Studio plug-in is an interface between Sablime and Visual Studio or other supporting applications for Windows. The supporting application is your Integrated Development Environment (IDE). The plug-in allows you to perform Sablime source control operations (such as check in, check out) from within the IDE. The Sablime plug-in SabVSPlugin - implements the Microsoft* Source Code Control API (SCC API) specification. The API allows IDEs to communicate with source code control providers like Sablime in common way. SabVSPlugin has been tested and is supported with following IDEs: Microsoft Visual Studio.NET 7.0 & 7.1 Microsoft Visual C++* 6.0 Microsoft Visual Basic* 6.0 Other IDEs that comply with the Microsoft SCC API might also work with SabVSPlugin. Refer to your IDE s documentation to determine whether or not it supports this interface. Requirements SabVSPlugin runs on a Windows NT*, Windows XP Professional, or Windows 2000 and higher platform that has Internet Explorer 5.0 or higher installed. 1 You will need Sablime web access (login) to install and use the plug-in. 1 You do not need to use Internet Explorer, but the plug-in uses some of the system libraries that are included with IE 5.0 or higher, and they must be present.

2 Installation SabVSPlugin is included in the Sablime v6.1 and Sablime for Windows sfw1.1 packages on the host machine. To install the plug-in onto a client, click the Settings button on the Web Sablime home screen. Then click "Download Sablime Plug-in for Visual Studio" near the upper-left corner of the screen and save the file to your local machine. Double-click on the saved file to install the plug-in. The installation wizard will guide you through the installation process. The next time you run the IDE (e.g. Visual Studio), the plug-in will automatically be loaded and available for use. When you install SabVSPlugin, it configures itself to be the Source Code Provider (SCC). If you need to change that setting, select Programs -> Sablime -> Change SCC Provider on the Start menu. To uninstall SabVSPlugin, launch the uninstall program by selecting Programs -> Sablime -> Uninstall SabVSPlugin from the Start menu. Upgrades When you install updates to your host Sablime, you may need to upgrade your SabVSPlugin. To do so, just follow the same instructions as above for Installation. Even if no upgrade was really needed, doing so is harmless. About the Plug-in In addition to the documentation provided here, you may also want to consult the documentation of your IDE. It may provide information on what SCC features are available and how they are presented to the user. The IDE (for example), not SabVSPlugin, lays out the SCC menu and the dialog boxes in its environment. Plug-in Environment SabVSPlugin is based on the client/server architecture and uses the Apache* web server as a host. The Sablime database resides on the host while the files you work on reside in an IDE workspace on your local machine. You can place some or all of the files in your workspace under Sablime. Terminology The following terminology are frequently used in the document: Project: To help organize and perform common tasks on the items you are developing, the IDE usually defines a project as a container to logically manage, build and debug the items that comprise an application. Visual Studio Plug-in Guide 2 April 2005

3 Product: Sablime terminology that most often corresponds to a single software application, though in some cases an application may be assembled from different "products". Product is the top-level organizational unit in Sablime. Generic: Sablime terminology representing a complete development cycle (release) of the product, from requirements through delivery and maintenance. Each product can have one or more generics. Source Node: A source node is a directory tree in Sablime database where Sablime stores source files associated with product and generic. Mapped Project: Associates a selected project in IDE with the specified Sablime product, generic and source node at the specified server location. Available Sablime commands & SCC API features The terminology used by the IDE to carry out tasks may differ from that used by Sablime. Table 1.0 compares some terms. Table 1.0. Commonly used term Sablime command (Visual Studio also uses these terms) CR - Change Request Add to source control Check Out Check In Undo Checkout Get Version Rename a file Remove from source control MR - Modification Request Addisrc/Addgsrc Edget Edput Unedget Sget/Getversion Source Source delete Table 1.1 lists the Sablime source commands available from the IDE using SabVSPlugin. Not all of the usual Sablime keywords for specific commands are available from IDE; only those that makes most sense in an IDE environment. In table 1.1 the Plug-in Configurable values are as follows: Yes [value] The keyword can be configured from within the IDE using Project Settings dialog box. Out of box configuration of plug-in defaults to value No [value] The specified keyword is not configurable and takes the specified value Automatic IDE/Plug-in determines the value based on project configuration or command invocation. Table 1.1 _ Keyword Description Plug-in Configurable Addisrc - Add files to Sablime Bfile Store As Binary Yes [auto-detect] Dir SDB Directory Location Automatic G Generic Yes Initsrc Current File Location Automatic Mr MR Number Yes Visual Studio Plug-in Guide 3 April 2005

4 Owner File Owner No [No owner] prompt Prompt for input No [n] Srf Source File Automatic Vct Version Control Tool Yes [SCCS] Addgsrc - Add files to Sablime Br Branch No [No value] Dir Directory Automatic G Generic [s1.0] Yes incldep Include Missing Depended-Upon MRs No [n] Initsrc Current File Location Automatic Mr MR Number Yes Mrs MRs for Specifying Version No [No value] Olddir Old Directory No [No value] Oldg Old Generic No [No value] Owner File Owner No [No owner] prompt Prompt for input [y] No [n] Srf Source Files Automatic Edget Check Out a file Dir Directory Automatic G Generic [s1.0] Yes Mr MR Number Yes prompt Prompt for input No [n] reserve Reserve Yes [n] Rm Remove Files [n] No [y] Srf Source Files Automatic Edput Check In a file Adep Auto Dependency Yes Com Comments File Yes Dir Directory Automatic extract Merge Extraction No [y] G Generic Yes lockout Merge Lockout No [n] Mr MR Number Yes overwrite Merge Overwrite No [n] prompt Prompt No [n] Reset Merge Reset No [n] Rm Remove Files No [n] showdep Show Dependencies First No [n] Srf Source Files Automatic Sget Get specified version of file Br Branch Yes [mr] Brdt Cutoff Date No [No value] Dir Directory Automatic G Generic Yes incldep Include Missing Depended-Upon MRs No [n] Kx Expand ID Keywords Yes [y] Mrs MR Numbers No [No value] prompt Prompt for input No [n] Rm Remove Files No [y] Srf Source Files Automatic SabVSPlugin also provides access to the fcreate command that allows you to create, accept and assign an MR to yourself from within the IDE. The available fields for the fcreate command are abstract and description, with the others being Visual Studio Plug-in Guide 4 April 2005

5 determined by Sablime defaults. SabVSPlugin does not implement every feature available in Microsoft SCC API. So, for some IDEs that use the SabVSPlugin, certain source control menus (like history) may not be available. The table 1.2 lists the features that are available from within the IDE based on SCC API and implementation of Sablime commands as listed in table 1.1. Table 1.2 _ Available SCC API Feature Implemented in SabVSPlugin Add project/files to Source Control Yes Open project from Source Control Yes Project Properties Yes Checkout Yes Check in Yes Undo Checkout Yes Get files Yes File Diff Yes (No Visual Diff) File History No Add files to project from Source Control No Remove files (delete from source control) No Rename project/files No Using the Plug-in Authenticating the User SabVSPlugin uses the same authentication mechanism (Basic Authentication) as used by Sablime web interface. When the IDE is invoked, the first time you add project files to Sablime or open the project that is controlled by Sablime, you will be asked to authenticate using the dialog box as shown in figure 1.3. Figure 1.3 For the IDE projects that are already mapped with Sablime, the plug-in will remember all the field values except for the password field. The password field value will be remembered only if Remember password checkbox is checked. Also Visual Studio Plug-in Guide 5 April 2005

6 the fields except User Name, Password and Remember password are protected for already mapped projects. The short description of the various fields on the form is: Web Sablime URL: Enter the URL that you use for invoking Sablime web interface. The format is Use HTTP Proxy Server: Check the checkbox if you are using proxy server for communicating with Sablime web server. This will enable Proxy Server and Port fields on the form. Proxy Server: Enter the host name of your proxy server. The field is enabled only if checkbox Use HTTP Proxy Server is checked. Port: Enter the port number of your proxy server. The field is enabled only if checkbox Use HTTP Proxy Server is checked. User Name: Enter the login name of the user for communicating with Sablime. Use the same login name as you uses for Sablime web interface. Password: Enter the password to authenticate user for using Sablime. Use the same password as you uses for Sablime web interface. Remember password: Check this if you want the plug-in to remember your password. It will be stored in a preference file, which is an xml file, in base64- encoded format. For greatest security, you should not to check this. Changing Sablime Settings When the IDE is invoked, the first time you add project files to Sablime, after authentication you will be asked to configure Sablime settings for the project using the Project Settings dialog box as shown in Figure 1.4 and 1.5. Figure 1.4 Visual Studio Plug-in Guide 6 April 2005

7 Figure 1.5 _ The project settings dialog box can also be invoked for an already mapped project in most IDEs through Sablime Properties source control menu. It has two tabs general and command options. The General tab has project specific options that map the project to the Sablime database, uniquely identifying product, generic and source node. The options are stored in the project preference file on the local machine. Each mapped project has its own project preference file named <Project Name>.sabscc. The short description of various fields on this tab is: Web Sablime URL: Read-only field that indicates the web server with which SabVSPlugin is communicating. Product: Drop-down list of available products on the Sablime server. The field is read-only for already mapped projects. The field is mandatory. Generic: Drop-down list of available generics for a specified product on the Sablime server. The field is read-only for already mapped projects. The field is mandatory. MR Number: Drop-down list of assigned MRs for a selected generic and product. The field is mandatory under certain scenarios like Adding project to Sablime. If unselected then certain source operations (check out, check in) will not be available. The New button beside this field allows you to fcreate an MR by specifying an abstract and description. The newly fcreated MR will be added to dropdown list. Local Path: Specifies the directory location on local machine from where the directory tree of the project (to be/already) mapped starts. It is mandatory field. The field is read-only and altered with the help of the Browse button on its side. The Browse button is only enabled, if plug-in is unable to Visual Studio Plug-in Guide 7 April 2005

8 determine local path by itself. Select Project (not shown in Fig 1.4): This is a list-box containing all the project files that are in Sablime database. The field is only visible when the user is trying to open a project from Sablime instead of local machine, or trying to map a local project with the one that already exist in Sablime. The determination of project files by Sablime is based on the file extension matching. If your IDE specifies particular file extension for a startup project file then you need to append that extension to the $VSEXTN variable in the wsab.conf file at your Sablime installation. Once the extension is appended, the project start-up file will be shown in the list box. VSEXTN comes initialized as follows, with Visual Studio extensions: $VSEXTN=".sln,.vbproj,.vbdproj,.vbp,.csproj,.csdproj,.vjsproj,.vc proj,.dsp,.mdp,.mak,.vfpproj,.vdp,.vdproj,.dbp,.vsmproj,.vsmacros,.hwproj,.etp,.etpproxy,.actproj,.atp,.dmp,.mdmp,.dsw"; The Command Options tab has Sablime source command specific options stored centrally for all mapped projects in plug-in global preference file on the local machine. Because the options are stored centrally, any change in command specific options will impact the command options of all mapped projects on local machine. The options can be overridden during command invocation in IDEs where Advanced menu is available for commands (e.g. check out, check in, get). The short description of various fields on this tab is: Auto Dependency: The field corresponds to adep keyword of the edput command and has values line-level, file-level and none. Comes preconfigured with line-level as selected value. Checkin Unchanged Files: SabVSPlugin provides a feature of comparing the checkout version of file with the one stored in database during check in. If the version is different from the one stored in Sablime, proceed with check in otherwise proceed with Undo Checkout. Thus it will prevent adding null deltas to the source file. This field enables or disables the above feature of SabVSPlugin. It has two values Undo Checkout and Checkin. If Undo Checkout is selected, which comes as pre-configured, the feature is enabled, preventing null deltas; with Checkin option the feature is disabled and check in will always proceed with file check in (as with traditional Sablime). Version Control Tool: The field corresponds to vct keyword of addisrc command and has values SCCS and SBCS. Comes pre-configured with SCCS as selected value. Store As Binary: The field corresponds to bfile keyword of addisrc command and has values auto-detect, yes and no. Comes preconfigured with auto-detect as selected value. Reserve Checkout: The field corresponds to reserve keyword of edget command and has values y and n. Comes pre-configured with n as selected value. If your product has temporary branch feature disabled then this field value will be ignored. Replace Writable Files: If the file that s being checked-out or gotten is writable on local machine, the field specifies plug-in what action needs to be taken: whether to discard local writable copy of a file or preserve the local copy and discard the one from Sablime. The possible values are Ask, Visual Studio Plug-in Guide 8 April 2005

9 Replace and Skip, comes pre-configured with Ask as selected value. If Ask is selected and file being checked-out is writable on local machine then the plug-in will prompt the user with the dialog box whether to overwrite the writable copy with the one being retrieved or keep the local one. For Replace option plug-in will always replace local copy with the one from Sablime while for Skip option plug-in will never replace local writable copy. Branch (not shown in Fig 1.5): The field corresponds to br keyword of sget command and has values br and mr. Comes pre-configured with mr as selected value. The option is only visible in IDE where Advanced option is available for get command. Synchronize Project Files with Sablime SabVSPlugin does not provide any automated action to synchronize the local copy of files with the one stored in Sablime database. Some IDE like Visual Studio does provide a menu that triggers Get Latest Version action for all files in project when opening the project to synchronize it. If such menu is not available one has to manually trigger the operation Get Latest Version of all files in project to synchronize local project files with one stored in Sablime whenever required. When to go Outside of the IDE User will need to go outside the IDE to perform any Sablime tasks that are not defined in section 1b. Also, they need to go outside of the IDE to use the SabVSPlugin non-configurable keywords for available Sablime commands. In order to go outside of the IDE, Sablime web interface can be invoked from most IDE by selecting menu Lucent Sablime from source control menu. If you do perform Sablime source control tasks outside the IDE, be sure to refresh the IDE display afterwards, to ensure that file status is updated and displayed correctly. Sablime Mapping IDE Project Files to its Source Node The plug-in does not give user a choice where the mapped project will be stored in the Sablime source node for a given product and generic. When adding a project to Sablime the IDE communicates to SabVSPlugin the project name. SabVSPlugin uses this project name as the root source node in Sablime, populating the project directory tree under it. For example, a project with name foo that has files under C:\com\src and C:\com\src\doc will have a source node populated in Sablime with directories foo, foo/src and foo/src/doc. In order to manage an already existing project in Sablime using SabVSPlugin, you may be required to re-arrange source files location in source node related to the project using Sablime source command to fulfill above criteria. Choosing Which Project Files to Put in Sablime Usually it s the IDE that decides and communicates to the plug-in which project files need to be in Sablime for a given project. However, if you need to decide yourself which project files need to be in Sablime, do not put any IDE-generated files (e.g..ncb,.clw or.opt files for Visual Studio) in your Sablime database. If you put certain build or view related files in Sablime those files are usually marked as Visual Studio Plug-in Guide 9 April 2005

10 read-only on local machine. That may result in build error or view display error because IDE is unable to update those files being read-only. Using the plug-in with Visual Studio.NET a) Overview This section guides you through common development tasks such as how to add a project/solution to Sablime, how to retrieve a project/solution from Sablime, and how to check files in and out on a regular basis. You can quickly get up to speed on the essential tasks by going though this section. Though the procedure is specifically targeted for Visual Studio.NET IDE, other SabVSPlugin compatible IDEs usually use similar procedures. b) Adding a project/solution to Sablime In this scenario, you want to create a new project/solution and then add the project/solution to Sablime or after you use Visual Studio.NET to create a new project/solution file, and some initial development, you want to add the project/solution to Sablime. The steps to add a project/solution to Sablime are: 1. Start Visual Studio.NET and create new project/solution or open the solution that you are already working with and want to add it to Sablime. 2. On the File menu, point to Source Control, and then click Add project/solution to Source Control. 3. You will be prompted with SabVSPlugin authentication dialog box. Fill out the form and click OK on the dialog box. 4. SabVSPlugin will then display the Project Settings dialog box, select the appropriate product, generic and MR number to map your project in Sablime and click OK on the dialog box. Though usually not required, you can also modify any source command options on command options tab before clicking OK button. Your project/solution with all associated source files are now placed under Sablime. The files are locked within Sablime as indicated by the lock symbol next to all the files in the Solution Explorer. The local working copy of files is assigned the read-only attribute to prevent you from working with them until you check out the files from Sablime. In case of any failures during the entire operation, you will be notified with appropriate message box. c) Opening a project/solution from Sablime In this scenario, another team member has created a project/solution and added it to Sablime. You have now joined the same project/solution team and would like to obtain the copy of project/solution for the first time to start working on it. The steps to open a project/solution from Sablime are: 1. Start Visual Studio.NET 2. On the File menu, point to Source Control, and then click Open From Source Control. 3. You will be prompted with SabVSPlugin authentication dialog box. Fill out the form and click OK on the dialog box. Visual Studio Plug-in Guide 10 April 2005

11 4. SabVSPlugin will then display the Project Settings dialog box, select the appropriate product, generic and MR number. Then locate the local path where you want to download your project on local machine. Now select the project that you want to work on from select project list box and click OK on the dialog box. Though usually not required, you can also modify any source command options on command options tab before clicking OK button. 5. You will now be prompted with Open Solution dialog box that has your solution/project as pre-selected, click OK on that dialog box. 6. The complete solution/project with all associated source files are now downloaded to your local machine. However, the files are locked in Sablime as indicated by lock symbol next to them in Solution Explorer. Note: To work on an already mapped solution/project with Sablime that exists on your local machine, you should open the local solution file. This approach is easy and less error prone. Do not use Open From Source Control menu in this scenario. Also, when you open the project/solution using the local file, to ensure you have the most updated version of project files, you can select the project/solution in Solution Explorer, right-click it, and click Get Latest Version (Recursive) d) Check Out a File When you modify a file by subsequently starting to edit a locked file, Visual Studio.NET has an automatic check out on edit feature that prompts you with Check Out For Edit dialog box to check out the file. Click the Check Out button and the file will be checked out for you. For checking out more than one file at the same time, right-click on solution/project file in solution explorer and select Check Out, select all the files that need to be checked out in the Check Out For Edit dialog box and click the Check Out button. e) Check In a File To check in the edited file, right-click an individual file within Solution Explorer and click Check In. For checking in more than one file at the same time, right-click on solution/project file in Solution Explorer and select Check In, select all the files that need to be checked in on the Check In dialog box and click Check In button. If there is a merge conflict for a file that is being checked in, Sablime will detect it and setup merge on local machine with appropriate message. You will need to go outside of the IDE to merge files. Also, merge set-up files (LD, CA and BK) are not deleted by subsequent successful merge/check in. f) Undo Checkout To undo checkout on a file that s already been checked out, right-click on a file within Solution Explorer and click Undo Checkout. To Undo Checkout on more than one file at the same time, right-click on solution/project file in Solution Explorer and select Undo Checkout, select all the files that need to be undo checkout on the Undo Checkout dialog box and click Undo Checkout button. Visual Studio Plug-in Guide 11 April 2005

12 g) Get a file SabVSPlugin can get one of the two different versions of a file from Sablime: Latest MR Branch version or Latest Official Branch version. It always defaults to Latest MR Branch version. To get the latest mr branch version of a file, right-click on a file within Solution Explorer and click Get Latest Version. To get latest mr branch version on more than one file at the same time, select all the files in Solution Explorer that need to be retrieved, right-click and select Get Latest Version. Complete project/solution will all related files can be retrieved by rightclicking project/solution file and selecting Get Latest Version (Recursive). To get the latest official branch version of a file, select project/solution file in Solution Explorer. On the File menu, point to Source Control and then click Get. On the Get dialog box, check all the files that need to be retrieved and click the Options toolbar menu. On command options dialog box, select Branch ofc and click OK. Then again click OK on the Get dialog box. The selected file s latest official branch version will be retrieved. h) Compare Versions To determine if a local version of a file differs from the latest mr branch version stored in Sablime, select a file in Solution Explorer. On the File menu, point to Source Control and then click Compare Versions. This will tell you if the file differs from the one stored in Sablime database or are same. SabVSPlugin does not support visual diffs and file history. i) Renaming and Deleting files Once the project/solution and its associated files are in source control, project/solution name and its associated file names cannot be renamed using Visual Studio menu. SabVSPlugin do not support this operation. Users are on their own for renaming project/solution and its associated files. Also, Deleting individual files or folders with Visual Studio is not automatically propagated to Sablime and vice-versa. As a result, deleting files from Visual Studio project/solution that are in Sablime requires similar action in Sablime using source command. And deleting files from Sablime that are part of Visual Studio project/solution requires similar action in Visual Studio. Known Problems and Limitations Authentication dialog box appears more than once for some projects: Some IDEs support a workspace view (solution view) where more than one project can be opened together. In such a case, if each project is stored at a separate source node for a specified product and generic in Sablime then your IDE will prompt for separate authentication dialog box for each such projects being opened. Entering comments in check out, undo check out dialog box does not work. SabVSPlugin supports comments for check in command only. However, certain IDEs (like Visual Studio) provide a comment field for almost all the Visual Studio Plug-in Guide 12 April 2005

13 source commands (like checkout, undo checkout). In such cases, SabVSPlugin will ignore the comment field the source commands other than check in. Changing command options in Project Settings dialog box for one project affects the settings of all other projects. Refer to the section Changing Sablime Settings, paragraph The Command options tab. When trying to open a project from source control using Visual Studio, if the project already exists in the selected local path then Visual Studio will prompt to overwrite the existing project with the one from Sablime using Overwrite dialog box. If the project does not exist in the selected local path then Overwrite dialog box will not pop up. Installing the plug-in leaves some files like mfc70.dll, msvcp70.dll, msvcr70.dll on other drive In some cases, for an unknown reason, when installing the plug-in it has been observed that the plug-in installs certain files on a drive other than the destination drive if more than one drive is available on machine. However, the files installed are harmless and if not modified will automatically be uninstalled when the plug-in is uninstalled. The plug-in does not delete BK, CA and LD files when file is checked-in When checking in the files if merge is required, the plug-in will setup merge extracting LD and CA files. However, these files will not be deleted by the plug-in after merge and subsequent check in. This is limitation of SabVSPlugin. The plug-in does not support bind or rebind option if available from within the IDE. The current version of the plug-in does not support bind or rebind operation. In order to rebind the project you need to do one of the following: a. If the IDE has an Open from Source Control menu, then select that menu and specify the same location where the current project exist. For Overwrite and Replace Writable Files dialog box that pops up during this operation, you can accept defaults and click OK to overwrite files from Sablime. b. If the IDE does not have an Open from Source Control menu, then using Sablime web interface: do a getversion of complete project node on local machine and then in IDE open project from local machine. It will prompt you to map local project with the one stored in Sablime. Select appropriate project from Sablime in project settings dialog box and the project will be rebound. Visual Studio Plug-in Guide 13 April 2005

14 When using the plug-in with Visual Studio, many times Reload Ignore dialog box pops up Visual Studio detects file changes that happen outside of IDE and prompts the user to reload or ignore the outside changes. In some cases SabVSPlugin does manipulate the file outside of IDE, so Visual Studio prompts user for Reload - Ignore dialog box. User can select either of the option in such cases, as the file has not actually been changed. Using the plug-in with Visual Studio, sometime an odd unedget error comes up when adding project to Sablime * When adding some projects to Sablime, Visual Studio sometime triggers the plug-in to unedget the file that was never added/checked-out in first place displaying unedget error dialog box. The file name is typically <Project/Solution Name>.vsscc. The cause of the problem is unknown and ignoring the message seems to work fine. * Microsoft, Visual Studio, Visual C++, Visual Basic, Windows, and Windows NT are trademarks or registered trademarks of Microsoft Corporation in the United States and other countries. * Apache is a trademark of the Apache Software Foundation. * Sablime is a registered trademark of Lucent Technologies. Contents copyright 2005 Lucent Technologies. Permission to photocopy in support of a licensed installation of Sablime is hereby granted. Visual Studio Plug-in Guide 14 April 2005