Although relocate leaves behind symbolic links to keep VOB namespace consistent, you probably need to make some additional adjustments in your development environment. Check existing views (config specs), build scripts, triggers, and any other tools that may rely on access to the relocated elements. Update these tools to access relocated elements at their new location, rather than relying on symbolic links.
The section Symbolic Links addresses potential problems associated with symbolic links. The section Cleanup Guidelines outlines the steps you must take to stabilize the development environment. Finally, Updating Directory Versions Manually offers techniques for fine-tuning the symbolic links left behind by relocate.
VOB symbolic links provide a powerful mechanism for linking MVFS objects, but you must be aware of their limitations:
In general, cleartool commands do not traverse VOB symbolic links. Instead, they operate on the link objects themselves. For example:
You cannot check out a VOB symbolic link, even if it points to an element.
A describe command lists information on a VOB symbolic link object, not on the object to which it points.
A mklabel -recurse command walks the entire subtree of a directory element, but it does not traverse any VOB symbolic links it encounters.
Config specs do not follow symbolic links to other VOBs.
Build scripts may include operations that fail on symbolic links.
If you move a relocated element with cleartool mv, any symbolic links from the source VOB are broken.
On UNIX hosts, broken symbolic links-those with nonexistent targets-are not visible to most file-system commands. These include those links that have accurate pathname information but point to elements not selected by the current view. The cleartool ls command lists these objects.
Views left to access relocated elements by means of symbolic links may have problems, even though they see relocated elements without difficulty. For example, you cannot check out a VOB symbolic link, even if it points to an element. There are several ways around this limitation, if a view with a more direct path to elements in the target VOB exists:
Reset the view's config spec to use absolute pathnames to the new VOB. This is the most thorough and predictable approach. But it may not be practical when many elements have been relocated and the config spec needs rules that specify a large number of individual elements.
Add labels to relocated versions, and configure the view to select these elements with a label-based rule.
Apply a particular branch type to relocated elements, and configure the view to select this branch.
To clean up after the relocate operation:
Use the view that was used for the relocate operation. Before adjusting config specs, modifying build rules, and so on, activate the same view, or the same config spec, that was in effect at relocate time.
In the source VOB, relocate completes its operation by checking in the parent directories of all relocated elements. Recall that this last checked-in directory version does not include symbolic links to relocated elements. Presumably, your view selects this version, in which relocated elements do not appear. Working in this view also allows you to track tools, build rules, and other potentially broken references to the relocated elements.
Check important and historical views to see whether symbolic links work. Some kinds of config specs are likely to have trouble:
Config specs with explicit pathname rules to relocated elements. (Config specs do not follow symbolic links to other VOBs.)
Config specs that use predominantly label-based rules. In this case, you may choose to add labels to relocated elements and their containing directories in the target VOB.
Config specs that look for relocated elements on a branch other than that on which the relocate operation was performed. Figure 29 shows the source VOB from Figure 24, expanded to include a second branch on the directory that contained the relocated elements. Note that relocate adds symbolic links only to versions on the branch used to select the element at relocate time. (See the key in Figure 23 here.)
Figure 29 Source VOB with Multiple Branches on Parent Directory
Fix broken views. After you find the problem config specs, use one of the techniques listed in Upgrading Views That Rely on Symbolic Links to make relocated elements visible again.
You can modify the results of a relocate operation by adding and removing VOB symbolic links to specific directory versions manually. However, these operations alter the intended results of relocate, and they are rarely necessary.
WARNING: The techniques described here are powerful and potentially dangerous. Do not use cleartool ln -nco or its companion command rmname -nco carelessly; they make permanent VOB changes without leaving behind an event history that you can trace easily. To use these commands, you must be the VOB owner or the privileged user.
In some cases, the VOB symbolic links that relocate creates automatically may have to be modified to point to their intended targets. An incorrect symbolic link in a specific directory version can be removed with cleartool rmname -nco and replaced with cleartool ln -nco.
relocate has to make an educated guess about the relationship between the source and target VOB roots and about the relationship between the source and target directories. The local host map, VOB mounting and naming conventions on UNIX, as well as drive assignment, disk sharing, and naming conventions on Windows can sometimes lead to an incorrect guess.
To help identify the sources and targets for symbolic links, relocate connects a symbolic link object to the target element object with a hyperlink of type HyperSlink. Use the cleartool describe command on the symbolic link to display information about this hyperlink, which can help to repair the symbolic link.
After you relocate elements, if you move any of them again with cleartool mv, symbolic links are not updated automatically. You can use this technique to update the links manually.
The following commands replace a relative symbolic link created by relocate with an alternative absolute pathname to the target VOB.
cd \bigdir
cleartool rmname -nco \bigdir@@\main\2\dir1
Modify non-checkedout directory version "\bigdir@@\main\2"? [no] yes
Link removed: "\bigdir@@\main\2\dir1"
cleartool ln -nco \new\proj2\dir1 \bigdir@@\main\2\dir1
Modify non-checkedout directory version "\bigdir@@\main\2"? [no] yes
Link created: "\bigdir@\main\2\dir1"
In Figure 25 here, relocate checks in a new version of the destination directory, and only that version catalogs the relocated elements. Now, consider this scenario:
You have a view, alh_port, that selects a previous version of the target directory (\new@@\main\2, for example).
You want the alh_port view to be able to see the newly relocated dir1 element at its new home, \new\dir1, rather than at its old location, \bigdir\dir1.
In a case like this, you can manually update previous versions of relocate's destination directory to catalog relocated elements. For example, to add dir1 to directory version \new@@\main\2:
Log on as the privileged user.
Create the VOB symbolic link. The following command requires special privileges because it modifies a directory version's contents without checking it out or changing its event history.
cd \new (and your working view must select some version of dir1)
cleartool ln -slink -nco dir1 \new@@\main\2\dir1
Modify non-checkedout directory version "\new@@\main\2"? [no] yes
Link created: "\new@@\main\2\dir1"
Figure 30 shows the effect of the cleartool ln -nco command. (See the key in Figure 23 here.)
Figure 30 Destination VOB After Modifying Old Version of Destination Directory
In Figure 24 here and Figure 27 here, the latest version of a relocated element's parent directory does not catalog that relocated element. In some circumstances, you may want to add such cataloging manually, in the form of symbolic links. For example, the following command sequence updates the from-directory version bigdir@@\main\3 (Figure 24) to see relocated directory dir1 at its new location:
cd \new
cleartool ln -slink -nco dir1 \bigdir@@\main\3\dir1
Modify non-checkedout directory version "\bigdir@@\main\3"? [no] yes
Link created: "\bigdir@@\main\3\dir1"
Feedback on the documentation in this site? We welcome any comments!
Copyright © 2001 by Rational Software Corporation. All rights reserved. |