Chapter 11          Working with Source Control   


This chapter describes the source control features available within iPlanet Application Builder.

The following topics are described in this chapter:

• About Source Control

• Configuring Source Control

• Invoking Commands from the Main Menu

• Sharing Settings Among Programmers

About Source Control

---

Source control lets you track multiple file revisions and offers the following advantages:

• Makes compiling and building easier.

  When you build a project, you can ensure that you use the latest version (or the correct version) of all files.

• Reduces storage space.

  Changes between file versions are stored as deltas, not as complete files. This also avoids the potential confusion of keeping separate files for each version.

• Prevents editing conflicts.

  With source control, you can check out a file and gain exclusive rights to edit it. Other developers can still view the file, but only you can change it.

Before you can use source control in iPlanet Application Builder, an underlying source control utility must be installed in your development environment. You must also configure iPlanet Application Builder for the particular utility you intend to use.

It is assumed that you a familiar with source control concepts and with the utility you intend to use. For more information, refer to the documentation that comes with your site's source control utility.

Configuring Source Control

---

Once a source control utility is available for you to use, you configure iPlanet Application Builder as follows:

1. Specify which source control utility to use.

2. Map the source control menu items in iPlanet Application Builder to corresponding command lines in the source control utility.

You perform these tasks from the Source Control tab in iPlanet Application Builder. From the Tools menu, choose Development Options and then click the Source Control tab. The following dialog box appears:

Specifying a Source Control Utility

Often, a network administrator sets up a particular source control utility for use in a networked environment. This setup may include defining user IDs for anyone who plans to use source control. Set up may also define policies for directory names and hierarchies. Keep this in mind as you specify a source control utility.

To specify a source control utility, use the drop-down list near the top of the Source Control tab and select one of the following supported utilities:

• CVS

• PVCS

• Revision Control System (RCS), available from the Free Software Foundation

• Microsoft Visual Source Safe

• A user-defined utility

Choose the source control utility installed on your machine. If you select a user-defined source control utility, no default command-mappings are provided. In this case, you need to map the menu items from scratch.

Defining Menu Items

In the Source Control tab, the Commands area shows command-line equivalents for the items in the Source Control submenu.

For example, suppose PVCS is the selected utility, as shown in the previous figure. The Show History text field contains the command:

vlog %b%e

In this example, when you choose Show History from the Source Control submenu, iPlanet Application Builder calls the PVCS utility, which in turn executes the vlog command. The characters %b and %e are macros, which are substituted for their current values at execution time. For more information, see Macro Definitions.

iPlanet Application Builder supplies default command-line equivalents. However, you can edit the text fields to suit your needs. You can also restore default values by pressing the Defaults button.

Before you edit text fields on the Source Control tab, make sure you understand the following topics:

• Relationship of Text Fields to Source Control Submenu

• Default Values for Command Lines

• Macro Definitions

Relationship of Text Fields to Source Control Submenu

The following table describes the text fields on the Source Control tab and their corresponding item on the Source Control submenu:

Table 11-1 Source Control Tab Text Fields 

Label in Source Control Tab	Equivalent Itemon Submenu	Description
Get	Get Latest Version ...	Updates selected files with their latest version from the source control system.
Check Out	Check Out ...	Checks out selected files from the source control system and opens them for editing.
Check In	Check In ...	Checks in selected files to the source control system, with a comment.
Check In, Locked	Check In ...	If you select the "Keep checked out" box, files remain checked out (locked) after changes are submitted.
Undo Check Out	Undo Check Out ...	Reverts the local version of selected files to the version in the source control system.
Add File	Add to Source Control ...	Adds files to the source control system.
Remove File	Remove from Source Control ...	Removes selected files from the source control system. Files are not removed from the project directory.
Show History	Show History ...	Displays revision history for selected files.
Start GUI	Source Control System ...	Displays the graphical user interface of the source control utility. This item is useful when you want to work directly with the utility.

Default Values for Command Lines

You can edit the command lines, or you can use the default values shown in the following table. A command is executed once for each of the selected files as if the command were run from the command line after making substitutions for macros. If you change a command line, the command line must conform the following conventions:

• it cannot request input; for example, it cannot prompt for a value or option

• it assumes that the command is run from the directory that contains the file

To debug your command line, you should check iPlanet Application Builder's message window to view the macro substitution. If your command does not work, you should check it outside of iPlanet Application Builder by attempting to execute the iAB-generated command from the command line.

CVS Commands
The following default commands are defined for CVS:

Table 11-2 CVS Default Commands

Label in Source Control Tab	CVS Command
Get	cvs co %r%e
Check Out	cvs co %r%e
Check In	cvs commit -m%Q %r%e
Check In, Locked
Undo Check Out
Add File	cvs add -m%Q %r%e
Remove File	cvs log %r%e
Show History
Start GUI

PVCS Commands
The following default commands are defined for PVCS:

Table 11-3 PVCS Default Commands

Label in Source Control Tab	PVCS Command
Get	get -y %b%e
Check Out	get -y -l %b%e
Check In	put -n -M%Q %b%e
Check In, Locked	put -n -M%Q -l %b%e
Undo Check Out	vcs -y -u %b%e
Add File	vcs -i -n -t%Q %b%e
Remove File	del /f %b%e
Show History	vlog %b%e
Start GUI

If you use PVCS, you must specify a configuration file, which is not included in the default commands. By default, PVCS places the default.cfg file in the following directory:

<pvcs_root>\pvcs\pvcsprop\pvcs\vm

You need to add this file to your commands using the -C option, as shown in the following examples:

Table 11-4 Example PVCS Commands with -c Option

Label in Source Control Tab	Example PVCS Command with -C option
Get	get -y -c"E:\Program Files\PVCS\pvcsprop\pvcs\vm\default.cfg" %b%e
Check Out	get -y -l -c"E:\Program Files\PVCS\pvcsprop\pvcs\vm\default.cfg" %b%e
Check In	put -c"E:\Program Files\PVCS\pvcsprop\pvcs\vm\default.cfg" -n -M%Q %b%e
Check In, Locked	put -c"E:\Program Files\PVCS\pvcsprop\pvcs\vm\default.cfg" -n -M%Q -l %b%e
Undo Check Out	vcs -c"E:\Program Files\PVCS\pvcsprop\pvcs\vm\default.cfg" -y -u %b%e
Add File	vcs -c"E:\Program Files\PVCS\pvcsprop\pvcs\vm\default.cfg" -i -t"new file" %b%e
Remove File	del /f %b%e
Show History	vlog -c"E:\Program Files\PVCS\pvcsprop\pvcs\vm\default.cfg" %b%e
Start GUI

If you do not enter a comment in a PVCS dialog box, you may receive an "out of memory" error from PVCS.

Visual Source Safe Commands
The following default commands are defined for Visual Source Safe:

Table 11-5 Visual Source Safe Default Commands

Label in Source Control Tab	Visual Source Safe Command
Get	ss GET -I- %r%e
Check Out	ss CHECKOUT -I- %r%e
Check In	ss UPDATE -I- -C%Q %r%e
Check In, Locked	ss UPDATE -I- -C%Q -K %r%e
Undo Check Out	ss UNCHECKOUT -I- -G- %r%e
Add File	ss ADD -I- -C%Q %r%e
Remove File	ss DELETE -I- %r%e
Show History	ss HISTORY -I- %r%e
Start GUI

Macro Definitions

You define source control commands using macros, which are substituted for actual values when the command is executed. You can choose from among the macros listed in the following table. Note that the examples provided are based on the following files:

• Source file is c:\iplanet\ias6\ias\apps\cdx\ListUsers.java

• Project file is c:\iplanet\ias6\ias\apps\cdx\cdx.iab

  
  

  Table 11-6 Macro Definitions 
  
  

  Macro	Substitution For	Example
  ${USER}	The value of the User Name field in the Source Control tab.
  %b	Basename. The name of the working file, minus the suffix.	c:\iplanet]ias6\ias\apps\cdx\ListUsers
  %d	Directory. The directory of the working file. It contains no filename and no drive letter. There is no trailing backslash.	\iplanet\ias6\ias\apps\cdx\
  %e	Extension. The suffix of the working file. It begins with a dot (.), unless it is null.	.java
  %p	Path. The directory path of the working file. Same as %d with a trailing backslash.	\iplanet\ias6\ias\apps\cdx\
  %Q	Text from the Comment box in the Check In dialog box. This macro is case-sensitive, so use an uppercase Q.
  %r	Root. The name of the working file, minus the suffix.	ListUsers
  %v	Volume. The volume drive of the working file. A letter and a colon.	c:
  %x	Project path. The path of the current .iab file. Typically this is the project directory.	\iplanet\ias6\ias\apps\cdx\
  %y	Project root. The name of the current .iab file.	cdx
  %%	Percent sign. Use this for a literal % in the command.

Setting Up the CVS Environment

To use CVS commands from iPlanet Application Builder, you must map your application source directory to a CVS archive. Typically, you manually copy the CVS directories and their contents from the client source tree to your application directory.

For example, to set up CVS source control for your Java code files, you would perform the following steps:

1. Set your CVSROOT environment variable.

      set CVSROOT=:pserver:user@cvsserver:/m/src

2. Change to a directory in which CVS is already set up and add the application directory tree at each level.

      cd D:\cvssource
      mkdir iplanet
      cvs add iplanet
      cd iplanet
      mkdir ias6
      cvs add ias6
      cd ias6
      mkdir ias
      cvs add ias
      cd ias
      mkdir apps
      cvs add apps
      cd apps
      mkdir cdx
      cvs add cdx

   If you use a FAT partitioned disk, you cannot use case-sensitive names because CVS is case sensitive but FAT directory names are not. In this case, you should use an NTFS partition.

3. From the command line, add a single file into your application directory.

      cd cdx
      cvs add dummy.txt

4. From the top-level, commit the file, which causes CVS to create a repository tree.

      cd D:\cvssource
      cvs commit

5. From your CVS client tree, such as D:\cvssource, copy the applications directory, such as iPlanet (and includes the file you just added), to your server directory; for example, D:\iPlanet.

Setting Up Visual Source Safe

To create a Visual Source Safe project and add a iPlanet Application Builder project, perform the following tasks:

1. Launch the Visual SourceSafe Explorer.

2. Right-click on the root folder ($/) and select "Create Project."

3. Specify the name of your Visual SourceSafe project; for example, NABApps, and click OK.

4. Right click on "Set Working Folder."

5. Specify or navigate to the directory that contains your iPlanet Application Builder projects; for example, D:\iplanet\ias6\ias\apps.

6. For each iPlanet Application Builder project you want to place under source control, right-click on your Visual SourceSafe project, select "Create Project" and specify the name of the iPlanet Application Builder project.

   For example, if you specified D:\iplanet\ias6\ias\apps in the previous step, when you specify cdx, D:\iplanet\ias6\ias\apps\cdx becomes the working folder.

You can add users for Visual SourceSafe using the Visual SourceSafe Admin program. The program creates an ss.ini file in the Users subdirectory in which Visual SourceSafe is installed. The file should contain at least the following entries:

; Your current SourceSafe project
Project = $iabapps
Force_Prj = Yes
...
[$/iabapps]
Dir (your_host_machine)=D:\iplanet\ias6\ias\apps

If you are creating multiple accounts, you can simply replace each user's ss.ini file with the one you created initially by copying it to their Users subdirectory.

Invoking Commands from the Main Menu

---

You invoke source control commands by pulling down the Tools menu, choosing the Source Control submenu, and then choosing one of its menu options. You can select one or more files from the Project window first, but selecting files is optional.

When you invoke a source control command, a Select Files dialog box appears. For example, suppose you are working in the HelloWorld project. If you highlight index.html in the Project window and then choose Add to Source Control, the following dialog box appears:

The Selected Files window, on the right, lists the full path names of any files you had previously selected. The window on the left lists all other files in the project.

Using the Select Files dialog box, you can change the set of files that you want to affect. For example, if you want to add more files to the source control system, you can highlight other listed files and then click the right arrow button. When you press OK, you apply the source control command to whatever files are listed in the Selected Files window.

Sharing Settings Among Programmers

---

In many cases, several programmers work on the same project, but each programmer might be using a different source control configuration. It may be desirable for everyone to share the same configuration settings.

To share these settings, one programmer can export them from the registry to a file. Other programmers can then import the resulting file into their respective registries.

The following procedure describes how to export source control settings:

1. Open the iPlanet registry editor by typing regedit from a DOS command prompt.

   The registry editor appears, and it displays the keys and values that apply to the iPlanet Application Server.

2. Locate the key denoted by the path

      HKEY_LOCAL_MACHINE\SOFTWARE\iPlanet\Application Builder\6.0\SCCS

   This key contains the command-line settings for source control in iPlanet Application Builder.

3. Select the SCCS folder.

4. From the Registry menu, choose Export Registry File.

5. Specify the name and location of the file.

   Do not specify a suffix. The .reg suffix is automatically appended to the file name.

Once the source control settings are exported, you can import them in either of the following ways:

• Double-click the previously exported .reg file.

• From a command prompt, run the command regedit filename, where filename is the previously exported .reg file.