9. Notes on Cross-Links

9. Notes on Cross-Links
This note clarifies and supplements the basic documentation of AccuRev’s cross-link feature.
Cross-Link Direction and Terminology
A cross-link is created in a workspace by the Include from Stream command (CLI: incl –b). The command name implies that a connection is being established from a specified backing stream to the workspace. But an existing cross-link is listed by the CLI command lsrules like this:
xlink <pathname> from <workspace> to <backing-stream>
That is, the direction of the cross-link “arrow” is the opposite of the direction implied by the “include from” command name. When describing a cross-link, we use this terminology:
In CLI messages, “cross-link” is abbreviated to “xlink”.
Cross-Links and Stream Namespaces
Each AccuRev stream (including snapshot streams and workspace streams) provides a namespace: a set of pathnames to some or all of the depot’s elements. For example:
\.\doc
\.\src
\.\tools
\.\doc\chap01.doc
\.\doc\chap02.doc
\.\src\commands.c
\.\src\topaz.c
\.\src\topaz.h
\.\tools\cmdshell
\.\tools\perl
\.\tools\python
\.\tools\tools.readme
\.\tools\cmdshell\bash
\.\tools\cmdshell\csh
\.\tools\cmdshell\bash\end.sh
\.\tools\cmdshell\bash\start.sh
\.\tools\cmdshell\csh\end.csh
\.\tools\cmdshell\csh\start.csh
\.\tools\perl\add_cr.pl
\.\tools\perl\remove_cr.pl
\.\tools\python\setup.py
\.\tools\python\vars.py
Since this set of depot-relative pathnames defines a hierarchy, it’s often clearer to list the pathnames component-by-component, like this:
\.\
doc
chap01.doc
chap02.doc
src
commands.c
topaz.c
topaz.h
tools
tools.readme
...
To locate an element, AccuRev interprets its specified pathname component-by-component (just like the operating system does). The cross-links facility provides a way to make AccuRev switch namespaces in the middle of the pathname-interpretation process.
Note:
For example, consider this pathname:
\.\tools\cmdshell\csh\end.csh
And suppose you’ve created a cross-link at subdirectory cmdshell, with workspace W as the source stream and stream S as the target stream. AccuRev will process the pathname, component-by-component, as illustrated here:
Pathname components up to and including the cross-linked component, are interpreted in the original (source stream) namespace.
Note that in workspace W, you continue to access the cross-linked element, subdirectory cmdshell, through its “local” name in the workspace’s namespace. It’s quite possible (but you don’t need to know) that this element has a different name — even a different pathname — in the target stream:
\.\tools\shell_scripts
\.\tools\common\scripts\
\.\scripting
... etc.
Pathname components below “cmdshell” are interpreted in the namespace of stream S, the target stream. For example, if script end.csh has been renamed in stream S to topaz_exit.csh, then that’s the name you must use in workspace W, as well:
\.\tools\cmdshell\csh\topaz_exit.csh
The File Browser and the CLI commands stat and files make this namespace-switching transparent: AccuRev shows you the element names and pathnames that will enable you to access the data from your current workspace or stream context.
Source Stream: Workspace vs. Dynamic Stream
The example in the preceding section uses a workspace as the “source stream”. The same pathname-interpretation principles apply if the source stream is a dynamic stream.
But the basic difference between workspace streams and dynamic streams affects the way cross-links work in them:
In a dynamic stream, the Include from Stream command incorporates all changes from the target stream immediately. This reflects the fact that a dynamic stream inherits versions from its backing stream automatically and instantly.
In a workspace, the Include from Stream command respects the workspace’s update level. That is, it incorporates only those changes that occurred in the target stream before the workspace’s most recent update. A subsequent Update command will bring in the more recent changes from the target stream.
Example: to see how cross-links work with a workspace’s update level, suppose that the following changes have been made in stream topaz_mnt:
directory element \.\tools\cmdshell\cmd has been Defunct’ed
directory element \.\tools\cmdshell\csh has been renamed to \.\tools\cmdshell\c_shell
file element \.\tools\cmdshell\c_shell\start.csh has been edited
You use the Include from Stream command to create a cross-link from your workspace to stream topaz_mnt, at pathname \.\tools\cmdshell. The immediate change to your workspace depends on its update level:
If the changes in stream topaz_mnt occurred after your workspace’s most recent update, you won’t see the changes immediately in your workspace: directory cmd will still exist, directory csh won’t be renamed to c_shell, and you won’t see the edits to file start.csh. But the status of these elements includes the (stale) indicator, showing that the changes are in the backing stream, waiting to be incorporated:
.\tools\cmdshell\cmd topaz\1 (9\1) (backed) (xlinked) (stale)
.\tools\cmdshell\csh topaz\1 (9\1) (backed) (xlinked) (stale)
.\tools\cmdshell\csh\start.csh topaz\2 (9\4) (backed) (xlinked) (stale)
At this point, performing an Update will bring the changes into the workspace.
If the changes in stream topaz_mnt occurred before your workspace’s most recent update, all those changes will be brought into the workspace immediately.
The procedure in the first bulleted paragraph can be described as “Include then Update”; the second bulleted paragraph’s case can be described as “Update then Include”. The final result is the same in both cases: the changes to the cross-linked elements in their new backing stream are incorporated into your workspace. We consider the second case to be an AccuRev best practice:
Best Practice:

Update your workspace before performing an Include from Stream command
If you Update first, other backing-stream changes won’t be “mixed in” with the Include from Stream changes during the next workspace update. Moreover, fully establishing the link from your workspace to the target stream will involve a single step (Include), rather than two steps (Include then Update).
Note: because it respects — but does not change — your workspace’s update level, Include from Stream more closely resembles the Populate command than the Update command.
Multiple Cross-Links: Chaining
AccuRev can traverse two or more cross-links in the same pathname. For example, you might use this pathname in workspace W:
/./aaa/bbb/ccc/DDD/eee/fff/GGG/hhh/foo.java
And suppose there are two cross-links:
At subdirectory DDD, a cross-link from workspace W to stream S1
At subdirectory GGG, a cross-link from stream S1 to stream S2
As AccuRev traverses the pathname component-by-component, it interprets the components as illustrated here. As it progresses down the pathname, AccuRev also traverses a “chain” of cross-links:
“Chaining” of cross-links can continue to any number of levels. The same principle applies repeatedly: a cross-linked pathname component is interpreted in the source stream’s namespace; subsequent non-cross-linked components are interpreted in the target stream’s namespace.
But you must take care when “chaining” cross-links in this way. It is possible to create ambiguous configurations, which AccuRev handles by removing the affected elements. See Cross-Link Overlaps.
A special case of cross-link chaining occurs when you create a configuration in which two or more cross-links occur at the same pathname component. For example, consider again this pathname:
\.\tools\cmdshell\csh\end.csh
And suppose there is a chain of two cross-links at the same pathname component:
At subdirectory cmdshell, a cross-link from workspace W to stream S1
At subdirectory cmdshell, a cross-link from stream S1 to stream S2
In workspace W, the subdirectory will continue to have its “original” name, cmdshell. But the subtree under the subdirectory will come from the stream S2 namespace. By extension, you could chain any number of cross-links at the cmdshell component: W > S1 > S2 > S3 > S4 ... As above, the directory retains its “original” name in the workspace, and the workspace sees the directory’s subtree as it exists in the final target stream.
Double Vision: Seeing an Element Multiple Times in a Workspace
One consequence of AccuRev’s cross-link facility is that two (or more) different versions of the same element can appear at different pathnames in the same workspace or stream. We call this phenomenon double vision. This is not an error — at least, not from AccuRev’s perspective. Seeing the same element twice might be exactly what you intended, or it might signify that you’ve left some refactoring work unfinished.
Here’s an example: suppose you are tasked with doing some cleanup on the Topaz project’s development tree:
Move file tools.readme to the depot’s root directory, and rename it to README-tools.txt.
You perform this work in your workspace, named topaz_refact. But when the dust settles, you find that the programs in the tools subdirectory no longer work. You are not sure whether the problem is in the tools directory or the src directory. So you decide to “back out” your refactoring of the tools directory, by cross-linking to the known-to-work version of the tools directory in snapshot stream topaz_2.3.9.
Now, you have two different versions of the “README” element in your workspace! In your refactoring, you created a new version in your workspace, at pathname \.\README-tools.txt:
But your workspace now cross-links to the Release 2.3.9 version of the tools subdirectory, which contains the Release 2.3.9 version of the same element, at pathname \.\tools\tools.readme:
This case of double-vision is clearly an error, reflecting the fact that your refactoring work is still ongoing. In other cases, you might want two (or more) versions of a commonly used source file, say topaz.h, to appear in a workspace. Perhaps several different versions of the file are required, in order to build different executables using that file. Version skew is the executables’ other dependencies might mandate the different versions of topaz.h.
Double Vision and the ‘accurev name’ Command
The accurev name command lists the pathname for a given element (specified by element-ID) in your workspace. It can also list the pathname for a specific version of an element, or the version in a specific stream:
accurev name -e 28
accurev name -v topaz_mnt -e 116
In a double vision situation, the name command can list all of an element’s pathnames in a workspace or stream:
> accurev name -e 28 -v topaz_refact
\.\tools\tools.readme
\.\README-tools.txt
Cross-Link Overlaps
Section Multiple Cross-Links: Chaining describes how a set of cross-links can define a “chain” of backing streams to be used at different components in a pathname:
Chaining works correctly if each switch to the next link in the chain occurs at the same pathname component or at a lower component. But here’s a situation that violates this rule:
In this case, the second link in the cross-link chain (S1 > S2) occurs at a higher pathname component, DDD, than the first link (W > S1, at component GGG). AccuRev recognizes this situation as a cross-link overlap.
When a workspace that has a cross-link overlap gets updated, AccuRev removes the subtree below the component where the first link was created.



 
 

Micro Focus