Order Number: ??--?????--??
DThis is a guide for the development environment package used within OpenVMS engineering.
EThis guide covers the common components and normal operations of the VOpenVMS Development Environment system, including an introduction and overview of the &OpenVMS Development Environment (VDE).
WThe OpenVMS Development Environment package is used within various Digital engineering +organizations, including the OpenVMS group.
-Revision/Update Information:<This manual supersedes the Guide to Using VDE, Version 1.4-n
"Software Version:VDE Version 1.5-0
*Operating System Version:1OpenVMS Alpha Version 6.2 OpenVMS VAX Version 6.2
EDigital Equipment Corporation Maynard, Massachusetts
?The following are trademarks of Digital Equipment Corporation: HBookreader, DEC Notes, DECdirect, DECwindows, Digital, OpenVMS, OpenVMS BCluster, VAX, VAX Document, VMScluster, VMS, and the DIGITAL logo.
)The following are third-party trademarks:
?Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are ;registered trademarks of the Open Software Foundation, Inc.
CAll other trademarks and registered trademarks are the property of their respective holders.
, 4
| CContents | =Index |
CThis manual is intended for users who want to learn more about the :OpenVMS Development Environment, or about the VDE utility.5
LThis document contains a guide to the OpenVMS Development Environment (VDE) ?package, and to the VDE command interface utility. It provides <an overview of VDE, and the various commands used to fetch, Dreserve, replace and otherwise access and maintain the modules in a VDE library.
7For a basic understanding of the VDE command interface Gutility, and the operations commonly performed by users, one need only ╗read Chapter 1, Chapter 2, and Chapter 3. |
.This guide contains the following information:
CIn this manual, every use of OpenVMS Alpha means the OpenVMS Alpha Aoperating system, every use of OpenVMS VAX means the OpenVMS VAX :operating system, and every use of OpenVMS means both the DOpenVMS Alpha operating system and the OpenVMS VAX operating system.
2The following conventions are used in this manual:
| Ctrl/ x | A sequence such as Ctrl/N x indicates that you must hold down the key labeled Ctrl while 8 you press another key or a pointing device button. |
| PF1 x | A sequence such as PF1I x indicates that you must first press and release the key K labeled PF1, then press and release another key or a pointing device button. |
| GOLD x | A sequence such as GOLDI x indicates that you must first press and release the key K defined GOLD, then press and release another key. GOLD key sequences L can also have a slash (/), dash (-), or underscore (_) as a delimiter in EVE commands. |
| [Return] | K In examples, a key name enclosed in a box indicates that you press a J key on the keyboard. (In text, a key name is not enclosed in a box.) |
| ... | G A horizontal ellipsis in examples indicates one of the following possibilities:
|
| . . . | N A vertical ellipsis indicates the omission of items from a code example N or command format; the items are omitted because they are not important # to the topic being discussed. |
| ( ) | L In format descriptions, parentheses indicate that, if you choose more C than one option, you must enclose the choices in parentheses. |
| [ ] | K In format descriptions, brackets indicate optional elements. You can K choose one, none, or all of the options. (Brackets are not optional, D however, in the syntax of a directory name in an OpenVMS file I specification, or in the syntax of a substring specification in an assignment statement.) |
| { } | L In format descriptions, braces surround a required choice of options; 0 you must choose one of the options listed. |
| $ boldface text | M Boldface text represents the introduction of a new term or the name of - an argument, an attribute, or a reason.N Boldface text is also used to show user input in Bookreader versions of the manual. |
| italic text | M Italic text emphasizes important information, indicates variables, and H indicates complete titles of manuals. Italic text also represents J information that can vary in system messages (for example, Internal error> number), command lines (for example, /PRODUCER=5 name), and command parameters in text. |
| UPPERCASE TEXT | M Uppercase text indicates a command, the name of a routine, the name of 9 a file, or the abbreviation for a system privilege. |
| - | K A hyphen in code examples indicates that additional arguments to the 4 request are provided on the line that follows. |
| numbers | M All numbers in text are assumed to be decimal, unless otherwise noted. J Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated. |
| mouse | The termM mouse refers to any pointing device, such as a mouse, a puck, or a stylus. |
| MB1, MB2, MB3 | J MB1 indicates the left mouse button, MB2 indicates the middle mouse L button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.) |
| PB1, PB2, PB3, PB4 | : PB1, PB2, PB3, and PB4 indicate buttons on the puck. |
| SB, SB | / SB and SB indicate buttons on the stylus. |
HOne of the most important tasks found in any large software engineering Geffort involves the coordination, tracking, maintenance and protection Rof the source files. OpenVMS engineering uses the OpenVMS Development Environment 9(VDE) package for these purposes, and for arcane reasons ?refers to the aggregate collection of OpenVMS source files and 5source libraries as the Master Pack.
OThe OpenVMS Development Environment (VDE) package is the set of tools that the BOpenVMS development group uses to control and to track changes to 5the multiple VDE libraries that comprise the OpenVMS Master Pack.R
>VDE is tailored for medium to large-scale source code control Fenvironments, and it provides capabilities and controls useful within 7the OpenVMS development environment. Among other uses, 6VDE is used to coordinate all access to the libraries #containing the OpenVMS source code.
3VDE provides various user interfaces including the <VDE1 command interface, and the Mosaic and Motif graphical user interfaces.F(Information on the Motif and WWW/Mosaic graphical user interfaces is uincluded in Chapter 10; this chapter describes the command interface.)
=The VDE command interface can be invoked directly at the DCL =prompt. VDE can also execute one or more semicolon-seperated Dcommands directly at DCL, and will return back to DCL after command completion.ALonger command lines can be broken across lines using the hyphen .character; the command continuation character."test suite library, respectively.)
+An example of a single VDE command follows:
|
" 6$ VDE RESERVE/STREAM=FRED [ACC]FOO.MAR "Remark string" |
6An example of a series of simple VDE commands follows:
|
" $ VDE5VDEä RESERVE/STREAM=FRED [ACC]FOO.MAR "Remark string"VDEä SHOW GENERATION [ACC]* VDEä EXIT$ |
FWhen either command is prompting for commands, there are a variety of Bfunctions available. One can use the keyboard arrow keys for line (editing and command line recall, and one:can also define keyboard keys to invoke specific commands.
1VDE2 A kept subprocess starts the VDE 8utility in a subprocess the first time one uses the VDE <command in a given process, and each subsequent VDE command E(with /KEPT_PROCESS specified or defaulted) attaches to the existing =subprocess to execute VDE commands. As a result, the work of 8activating the VDE utility and connecting to the source Econtrol database (which is a relatively slow operation) is done only 9for the first VDE command one enters in a given process. ?Subsequent VDE commands that access the database are then much 7faster. In addition, the kept subprocess retains state Einformation---such as default settings, and even the initial process Cdefault directory---as long as that subprocess is active. The kept ?subprocess is implicitly terminated when the parent process is Aterminated. The kept subprocess is explicitly terminated via the VDE@EXIT/KEPT_PROCESS command. Further information on this topic is Kincluded in Section 1.9.1.
| N P 1 In certain existing installations of 4 VDE, VDE users have access to three command , interfaces: VDE, VSC, and VTSC. The P command sets, the operations, and the personalities are all effectively N identical; the salient differences among the three command interfaces O include the library chosen for initial access, and the default setting 6 of the /KEPT_PROCESS qualifier. VDE, VSC, and : VTSC command sets and capabilities are completely N interchangeable. Any applicable differences will be explicitly called O out. Appendix B.F2 VSC defaults to the use of K a kept subprocess. This can be overridden with the /NOKEPT_PROCESS qualifier. |
HThe remainder of this chapter discusses some high-level concepts needed @when working with the OpenVMS VAX library, and some features of VDE that make this easier.
iSection 1.3 discusses the basic unit of source control: the module. gModules are organized into facilities. Section 1.4 discusses how [parallel development is organized, while Section 1.5 and bSection 1.7 describe how changes to modules are propogated.
iFacilities are grouped into Streams, and Section 1.4 describes the concept of a stream.
<VDE can be extended for user requirements using a scripting Emechanism. Some scripts, such as those needed to build a module, are Frequired. Others, such as the script that triggers wheneever a module Eis replaced, are optional. A brief overview of scripts is located in 1Section 1.8.
=VDE has a number of convenience features. For information on Econvenience features such as contexts, session initialization files, @user-specified key definitions, and user-specified default text Heditors, see Section 1.9.S
EThe OpenVMS VAX library contains over 22,000 source modules. As this Cis far too many modules for anyone to reasonably keep track of the ?various associations, the library is broken down into over 200 Efacilities, and each module belongs to one of those 8facilities. The VDE system uses the following syntax to 6specify a module and the facility to which it belongs:
|
" [fac-name]mod-name.type-name |
HFor example, [FACIL]MOD.TYP refers to module MOD.TYP in facility FACIL. <This syntax is accepted on VDE commands and is displayed in VDE output.
<If you omit the bracketed facility name, as in MOD.TYP, VDE Dassumes that the module belongs to the default facility, provided a Gdefault facility is defined. You specify the default facility for your *VDE session with the SET FACILITY command:
|
" VDEä SET FACILITY SYS |
FStreams are central to the source control system. Each stream holds a Cparticular generation of a module, and each stream has information Hassociated that controls the propogation of changes among releases, the Gselection of the appropriate CMS generation numbers, the list of users Ethat review changes, the list of users that are notified of changes, and various other attributes.
>The OpenVMS Development Group usually has several versions of >OpenVMS under development at any one time. These versions are 7called development streams, or simply Gstreams. Examples of development streams include past ?versions of OpenVMS (such as V4.7 or V5.0), versions currently Cunder development (often with code names such as DRAGON or EAGLE), @off-to-the-side development streams (often called "variant ?streams" or "variant threads"), and base levels.
6As a VDE user, you must always reserve modules from a Fspecified stream, and you must then later replace the updated modules =into the same stream. As a result, many VDE commands require Cyou to specify the development stream to which the commands should apply.
HMany such commands allow you to specify the development stream with the F/STREAM qualifier. If you omit this qualifier or the command does not Faccept it, the command acts on the default stream, provided a default Hstream is defined. One specifies the default development stream for the (VDE session with the SET STREAM command:
|
" VDEä SET STREAM EPSILON |
1VDE and VDE can store multiple instances of each 6source module in a library. Each instance is called a *generation of the module.
EModule generations are analogous to a railroad network---some tracks Hcan branch off and run parallel to the mainline track, some sidings can Gdiverge off the mainline, and some sidings can reconnect back into the mainline.
GEach generation can represent a current or past instance of the module Eas it was at some point during its historical development. Different Egenerations can also represent variants of the module that belong to Adifferent development streams being developed concurrently. Each Hgeneration of a module is created by reserving the previous generation, Eediting that generation to produce the new generation, and replacing Hthe new generation into the library. Each generation (except the first) Athus has a predecessor. A given generation may have zero or more >successors. If there are multiple successors, these successor Ggenerations represent variants of the module for different development streams.
HFor each module that is represented in a given stream, there is exactly Hone generation that stores the current contents of that module for that 5stream. This generation is called the latest Egeneration of the module for the stream. The source control Hdatabase records what generation of each module belongs to each stream. FA module need not have a latest generation for every stream, however. HFor example, a recently added module will not be used in older versions >of OpenVMS and will therefore not have latest generations for those streams.N
;VDE provides a mechanism by which source code for multiple Harchitectures can be maintained. As it is possible that the same module =name is used in each architecture, VDE allows the facilities =and the module names to overlap. By default, VDE assumes all (source code is architecture-independent.
<VDE allows a suitably privileged user to create one or more .architecture-dependent architecture roots, or @arch-roots. Each arch-root stores zero or more <architecture-dependent modules in an architecture-dependent Dfacility---in effect, the structure of each arch-root parallels the "structure of the main source pool.
EFor further information on (arch-roots) and on architecture support, =see Chapter 9.V
.VDE supports propogation and Cfolding. Propogation is an automatic process that Gcauses the replacement of a source module in the specified replacement Cstream, and into all successor streams; into all streams that have $descended from the specified stream.
=Folding is a manual form of propogation and is used when the <VDE automatic propogation is not feasible. A fold record is Ecreated as a reminder that a module must be manually propogated into parallel and successor streams.
@Folding records can be used to coordinate files across multiple @arch-roots. Automatic propogation of source code changes across ;multiple arch-roots is not supported as it is expected the ?architecture-specific modules will differ rather substantially.
BThe automatic propogation occurs in successor streams only if the Dmodule has not been changed in the successor stream---the change is Gpropogated only if the module is of the same generation. If the module Ahas changed---if the source code has diverged---in any successor Hstream, a fold record is created for each successor stream. Propogation &is based on module generation numbers.
BVarious types of scripts are optional and allow for site-specific Dprocessing. Specification of certain scripts is mandatory, as these 3scripts are used within VDE. For instance, the VDE VDE$BUILD utilityHrequires specific information when compiling and linking modules and it Gretrieves this information from the (mandatory) user-specified compile and link scripts.
<For further information on scripts and script creation, see ₧Section 5.8, Table 5-5, and the Script topics in the VDE Reference Manual.
| NextZ | Contents\ | Index |