Order Number: ??--?????--??
This is a guide for the development environment package used within OpenVMS engineering.
This guide covers the common components and normal operations of the OpenVMS Development Environment system, including an introduction and overview of the OpenVMS Development Environment (VDE).
The 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: OpenVMS Alpha Version 6.2 OpenVMS VAX Version 6.2
Digital Equipment Corporation Maynard, Massachusetts
The following are trademarks of Digital Equipment Corporation: Bookreader, DEC Notes, DECdirect, DECwindows, Digital, OpenVMS, OpenVMS Cluster, 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.
All other trademarks and registered trademarks are the property of their respective holders.
| Contents | Index |
This manual is intended for users who want to learn more about the OpenVMS Development Environment, or about the VDE utility.
This 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, reserve, replace and otherwise access and maintain the modules in a VDE library.
For a basic understanding of the VDE command interface utility, and the operations commonly performed by users, one need only read Chapter 1, Chapter 2, and Chapter 3. |
This guide contains the following information:
In this manual, every use of OpenVMS Alpha means the OpenVMS Alpha operating system, every use of OpenVMS VAX means the OpenVMS VAX operating system, and every use of OpenVMS means both the OpenVMS Alpha operating system and the OpenVMS VAX operating system.
The following conventions are used in this manual:
| Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. |
| PF1 x | A sequence such as PF1 x indicates that you must first press and release the key labeled PF1, then press and release another key or a pointing device button. |
| GOLD x | A sequence such as GOLD x indicates that you must first press and release the key defined GOLD, then press and release another key. GOLD key sequences can also have a slash (/), dash (-), or underscore (_) as a delimiter in EVE commands. |
| [Return] | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) |
| ... |
A horizontal ellipsis in examples indicates one of the following
possibilities:
|
|
.
. . |
A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed. |
| ( ) | In format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. |
| [ ] | In format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification, or in the syntax of a substring specification in an assignment statement.) |
| { } | In format descriptions, braces surround a required choice of options; you must choose one of the options listed. |
| boldface text |
Boldface text represents the introduction of a new term or the name of
an argument, an attribute, or a reason.
Boldface text is also used to show user input in Bookreader versions of the manual. |
| italic text | Italic text emphasizes important information, indicates variables, and indicates complete titles of manuals. Italic text also represents information that can vary in system messages (for example, Internal error number), command lines (for example, /PRODUCER= name), and command parameters in text. |
| UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. |
| - | A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows. |
| numbers | All numbers in text are assumed to be decimal, unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated. |
| mouse | The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus. |
| MB1, MB2, MB3 | MB1 indicates the left mouse button, MB2 indicates the middle mouse 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. |
One of the most important tasks found in any large software engineering effort involves the coordination, tracking, maintenance and protection of the source files. OpenVMS engineering uses the OpenVMS Development Environment (VDE) package for these purposes, and for arcane reasons refers to the aggregate collection of OpenVMS source files and source libraries as the Master Pack.
The OpenVMS Development Environment (VDE) package is the set of tools that the
OpenVMS development group uses to control and to track changes to
the multiple VDE libraries that comprise the OpenVMS
Master Pack.
1.1 What is VDE?
VDE is tailored for medium to large-scale source code control environments, and it provides capabilities and controls useful within the OpenVMS development environment. Among other uses, VDE is used to coordinate all access to the libraries containing the OpenVMS source code.
VDE provides various user interfaces including the VDE1 command interface, and the Mosaic and Motif graphical user interfaces. (Information on the Motif and WWW/Mosaic graphical user interfaces is included 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 commands directly at DCL, and will return back to DCL after command completion. Longer 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:
$ VDE RESERVE/STREAM=FRED [ACC]FOO.MAR "Remark string" |
An example of a series of simple VDE commands follows:
$ VDE VDE„ RESERVE/STREAM=FRED [ACC]FOO.MAR "Remark string" VDE„ SHOW GENERATION [ACC]* VDE„ EXIT $ |
When either command is prompting for commands, there are a variety of functions 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.
VDE2 A kept subprocess starts the VDE utility in a subprocess the first time one uses the VDE command in a given process, and each subsequent VDE command (with /KEPT_PROCESS specified or defaulted) attaches to the existing subprocess to execute VDE commands. As a result, the work of activating the VDE utility and connecting to the source control database (which is a relatively slow operation) is done only for the first VDE command one enters in a given process. Subsequent VDE commands that access the database are then much faster. In addition, the kept subprocess retains state information---such as default settings, and even the initial process default directory---as long as that subprocess is active. The kept subprocess is implicitly terminated when the parent process is terminated. The kept subprocess is explicitly terminated via the VDE EXIT/KEPT_PROCESS command. Further information on this topic is included in Section 1.9.1.
1 In certain existing installations of VDE, VDE users have access to three command interfaces: VDE, VSC, and VTSC. The command sets, the operations, and the personalities are all effectively identical; the salient differences among the three command interfaces include the library chosen for initial access, and the default setting of the /KEPT_PROCESS qualifier. VDE, VSC, and VTSC command sets and capabilities are completely interchangeable. Any applicable differences will be explicitly called out. Appendix B.2 VSC defaults to the use of a kept subprocess. This can be overridden with the /NOKEPT_PROCESS qualifier. |
1.2 VDE and the OpenVMS VAX Library
The 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.
Section 1.3 discusses the basic unit of source control: the module. Modules are organized into facilities. Section 1.4 discusses how parallel development is organized, while Section 1.5 and Section 1.7 describe how changes to modules are propogated.
Facilities are grouped into Streams, and Section 1.4 describes the concept of a stream.
VDE can be extended for user requirements using a scripting mechanism. Some scripts, such as those needed to build a module, are required. Others, such as the script that triggers wheneever a module is replaced, are optional. A brief overview of scripts is located in Section 1.8.
VDE has a number of convenience features. For information on
convenience features such as contexts, session initialization files,
user-specified key definitions, and user-specified default text
editors, see Section 1.9.
1.3 Modules and Facilities
The OpenVMS VAX library contains over 22,000 source modules. As this is far too many modules for anyone to reasonably keep track of the various associations, the library is broken down into over 200 facilities, and each module belongs to one of those facilities. The VDE system uses the following syntax to specify a module and the facility to which it belongs:
[fac-name]mod-name.type-name |
For 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 assumes that the module belongs to the default facility, provided a default facility is defined. You specify the default facility for your VDE session with the SET FACILITY command:
VDE„ SET FACILITY SYS |
Streams are central to the source control system. Each stream holds a particular generation of a module, and each stream has information associated that controls the propogation of changes among releases, the selection of the appropriate CMS generation numbers, the list of users that 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 called development streams, or simply streams. Examples of development streams include past versions of OpenVMS (such as V4.7 or V5.0), versions currently under 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.
As a VDE user, you must always reserve modules from a specified stream, and you must then later replace the updated modules into the same stream. As a result, many VDE commands require you to specify the development stream to which the commands should apply.
Many such commands allow you to specify the development stream with the /STREAM qualifier. If you omit this qualifier or the command does not accept it, the command acts on the default stream, provided a default stream is defined. One specifies the default development stream for the VDE session with the SET STREAM command:
VDE„ SET STREAM EPSILON |
VDE and VDE can store multiple instances of each source module in a library. Each instance is called a generation of the module.
Module generations are analogous to a railroad network---some tracks can branch off and run parallel to the mainline track, some sidings can diverge off the mainline, and some sidings can reconnect back into the mainline.
Each generation can represent a current or past instance of the module as it was at some point during its historical development. Different generations can also represent variants of the module that belong to different development streams being developed concurrently. Each generation of a module is created by reserving the previous generation, editing that generation to produce the new generation, and replacing the new generation into the library. Each generation (except the first) thus has a predecessor. A given generation may have zero or more successors. If there are multiple successors, these successor generations represent variants of the module for different development streams.
For each module that is represented in a given stream, there is exactly
one generation that stores the current contents of that module for that
stream. This generation is called the latest
generation of the module for the stream. The source control
database records what generation of each module belongs to each stream.
A module need not have a latest generation for every stream, however.
For example, a recently added module will not be used in older versions
of OpenVMS and will therefore not have latest generations for
those streams.
1.6 Architectures
VDE provides a mechanism by which source code for multiple architectures 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 facility---in effect, the structure of each arch-root parallels the structure of the main source pool.
For further information on (arch-roots) and on architecture support,
see Chapter 9.
1.7 Propogation and Folding
VDE supports propogation and folding. Propogation is an automatic process that causes the replacement of a source module in the specified replacement stream, 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 created 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.
The automatic propogation occurs in successor streams only if the module has not been changed in the successor stream---the change is propogated only if the module is of the same generation. If the module has changed---if the source code has diverged---in any successor stream, a fold record is created for each successor stream. Propogation is based on module generation numbers.
1.8 Customization Using Scripts
VDE allows extensive user tailoring using
scripts. A script allows you to easily perform a
user-specified action as a part of a script-specific VDE
operation. For instance, VDE invokes the replace script when
a module is replaced in the VDE database.
Various types of scripts are optional and allow for site-specific processing. Specification of certain scripts is mandatory, as these scripts are used within VDE. For instance, the VDE VDE$BUILD utility requires specific information when compiling and linking modules and it retrieves 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.
| Next | Contents | Index |