#F>========================================================================= # localdev.README # RCS: $Revision: 1.40 $ $Date: 2002/05/20 17:38:44 $ $Author: prentice $ #========================================DISCLAIMER========================= # This file has been developed by and/or for the U.S. government within the # Forecast Systems Laboratory by government and/or contract personnel. # As required by government regulations, this file is in the public # domain, and is furnished "as is", without technical support, and with # no warranty, express or implied, as to its usefulness for any purpose. #F>>=====================================description (optional)============= # This file provides an overview of the localdev packege. #F>>>======================================================================= PACKAGE IDENTIFICATION ============================= This software package and its documentation have been developed at: Forecast Systems Laboratory NOAA/ERL/FSL 325 Broadway Boulder, CO 80303 Modernization Division Advanced Development Project Localdev Development Package The author of the package is: Robert Prentice (CIRA, under collaborative agreement with FSL) prentice@fsl.noaa.gov Although the laboratory can assume no responsibility for the use or technical support of this package (see disclaimer below), the author would appreciate hearing about any problems or difficulties you have had in using this package. It will be in the best interests of the laboratory and all involved if such problems are corrected within future releases of this package. RELEASE INFORMATION ============================= Release 2.06 ------------ This is a maintenance release the that eliminates problems found when testing and using prior releases, and also contains some performance enhancements. This package has been tested on Linux and HP-UX platforms. Localdev will run with Perl release 5.004 or higher, though the regression tests in the tst subdirectory require Perl release 5.6 or higher. This release does not provide prebuilt versions of GNU utilities upon which its operation depends. The complete source releases of these aggregates are provided for your use. The installation process requires you to either build the provided aggregates in platform-specific directories within the localdev release hierarchy, or place symbolic links therein that allow users on each platform to access the aggregate packages that are already installed on their machines. The following scripts are included in this release: Setup Scripts dv-config : manage development area configuration dv-help : display general information about localdev scripts dv-scope : define an account's localdev scope and associated modes dv-select : choose global settings and current development area Development Scripts dv-commit: submit files to the current source area dv-dir: list, create, and manipulate directories dv-expand: intelligently expand tabs dv-file: register and manipulate source files dv-list: list information about source files dv-lock: stage and lock source files for modification dv-merge: merge files from one source area to another dv-path: find localdev-relevant locations dv-revert: unlock and unstage source files dv-shelve: reversibly designate source files/dirs as unused dv-stage: isolate build area files (by creating local copies) dv-state: display or set source area state dv-sync: synchronize a build area with its source area dv-tag: tag revisions of source area files Tool Access Scripts cmp: access underlying cmp comparison utility (GNU) diff: access underlying diff comparison utility (GNU) diff3: access underlying diff3 comparison utility (GNU) patch: access underlying patch utility (GNU) rcs: restricted access to underlying rcs control utility (RCS) ci: restricted access to underlying ci checkin utility (RCS) co: restricted access to underlying co checkout utility (RCS) rcsdiff: access underlying rcsdiff comparison utility (RCS) rlog: access underlying rlog revision control utility (RCS) Maintenance Scripts dv-buildarea: list, create, and manipulate build areas dv-hub: list, create, and manipulate hubs dv-import: import source files or prebuilt/installed files dv-repair: repair (or validate) current source area dv-sever: sever locks that others have placed on files dv-sourcearea: list, create, and manipulate source areas dv-stamp: list and modify commit stamps Known Problems and Limitations ------------------------------ >> localdev scripts have not been ported to Windows platforms >> The CM interface is unavailable in release 2.x, but this release is inter-operable with 1.x releases, so CM support can still be provided to source and build areas that are created in 1.x and subsequently created as interoperable in 2.x. (Note that such source areas must be repaired in 2.x before use.) CM support will again be provided in a later release. Significant Changes since Prior Releases ---------------------------------------- Release 2.06 >> dv-path now consistently reports source area paths that correspond exactly to build area paths >> dv-sync listing output (generated when invoked with no arguments) now more clearly indicates that synchronization is NOT taking place. A directory argument must be specified in order to activate synchronization. >> All commands that previously supported a quiet option now also support a verbose option. You can thus set your default option (via dv-select) to be either quiet or not, and then override this default selectively using quiet or verbose options on the command-line. >> The --find and --since arguments supported by many commands have been changed in meaning so as to make them easier to use and to implement. If one or more file or directory relpath arguments are also specified, then --find and --since apply to all of them (--find only to directories). Otherwise, --find and --since apply recursively to the current working directory. These options now correctly always compare with the time of the last committed revision, not the build area file. Note that these comparisons rely on the fact that source area files are given modification times that match the last committed revision time. >> dv-sync has been altered to normally provide more verbose output that is more in line with what other commands provide. Error handling has been improved to more consistently generate denial messages when specified directories do not exist. >> The force option on dv-sync now works. Use of this option will cause staged files that are not locked, whether writable or not, to be discarded. >> Some obscure failures were eliminated by forcing variable settings that RCS uses to determine user identity. This change makes it much more difficult to spoof an identity. Release 2.05 >> dv-buildarea now correctly lists build areas when invoked by developers wihout parameters. This had previously worked only for hub owners. >> Several types of failures associated with moving, copying, or deleting hubs and source areas have been eliminated. >> Directories containing build areas need no longer be owned, but they must (obviously) be readable and writable. >> a localdev initialization fix eliminates creation of bogus RCS links in source areas (which had been detected following dv-dir execution). >> Varous internal changes have been made to support automated regression testing of releases. This will improve reliability and speed enhancement. Release 2.04 >> dv-repair: corrected accumulation of links in repetitive directory reads >> dv-sync: eliminated incorrect link removal >> dv-buildarea: syntax without arguments now works >> dv-repair: corrected problems associated with repairing .auto_stage files >> dv-merge: handling of binary files corrected - was generating erroneous corruption messages and possibly corrupting binary files with terminators. >> dv-merge was enhanced to support INCLUDED and EXCLUDED merge status values -- hence, 'dv-merge -x -s excluded relpath' will cause a file to be excluded from future merges until overridden by a similar but inverse request: 'dv-merge -x -s included relpath'. Release 2.02 >> Recovery from a manual copying of a build area can now be accomplished using 'dv-sync .' from a top-level build area directory. >> Several messages have been improved, and a number of rarely encountered errors have been eliminated. Release 2.01 >> Installation/release scripts were corrected to install dv-merge, and to correct some installed links. >> An uninitialized variable was causing warnings when diff was run. It has been initialized. Release 2.0 >> Baselines have been replaced by source areas >> Staging areas have been replaced by build areas >> Hubs are now registered with a localdev installation >> New comands dv-hub, dv-sourcearea, dv-buildarea, dv-dir, and dv-file replace numerous other administrative commands for creating and manipulating source areas, build areas, directories, and files. These are much more conprehensive commands. >> New script dv-merge provides automatic migration/merge between production areas >> New script dv-stamp supports commit stamp management >> dv-tag has been simplified (tasks off-loaded to dv-stamp and dv-merge) >> Numerous operations including the creation of directories, locking or registering files, and staging files, are no longer prohibited when a source area state is 'stable' (or in some cases 'closed') state. Only when a change affects file revisions used in builds are they considered to be a source area change subject to being blocked. >> Directory creation is no longer a privileged operation. This allows merges to automatically create directories. >> Files must now be registered (with dv-file) before being committed. Filenames ignored when seeking eligible files for registration are now configured by specifying UNIX-style glob patterns. >> The configurable unique directory constraint on source areas is now enforced. >> dv-commit has a new option allowing disabling of commit checks, and works in conjunction with dv-merge >> Account configuration, as supported by dv-scope, has changed to support use of a single configuration file per account. Although the use of the LOCALDEV_TASK variable is still supported for backward compatibility, a new variable, LDEV_MODE, is also available. Each session must now select a localdev mode via either of these variables. Each mode is associated with a single development area. dv-select can still be used to change such associations. New modes are created automatically when new source and build areas are created. >> An inter-operability mode is supported by dv-sourcearea and dv-buildarea. This allows existing 1.x baselines and staging areas to also act as 2.x source and build areas. They must be created in 2.x using a special inter-operability option, and are accessed via 2.x hubs that are independent of 1.x hubs. >> dv-scope automatically generates a 2.x account configuration file from existing 1.x configuration files. This happens when 'dv-scope -m' is run. >> Access scripts have been renamed to match their actual underlying counterparts, making their access transparent >> Usage info is now paged; succinct usage examples were added; documentation overall has been updated and improved >> Documentation clarifies owner account terminology >> Build area settings are now set via dv-select instead of via dv-config >> Obsolete and unimplemented commands were eliminated from the documentation >> dv-file can move, copy, or delete multiple files (following UNIX-like destination syntax), including any combination of committed, registered, or uncommitted files. The prevalence of confirmation requests have been reduced in dv-file and dv-dir. >> dv-path has been simplified, and its documentation corrected >> Unstaging capability has been moved into dv-stage. >> Platform computation has been refined (now use native methods) >> The localdev installation process has been automated >> The global confirm option has been eliminated (noop remains) >> The release package no longer contains prebuilt aggregates >> Changes have been made to better handle failures to write configuration files, and to detect corruption of configuration files. >> The status information provided by dv-lisy has been simplified, and made more accurate in cases where multiple build areas are in use. >> Numerous internal changes have been made to improve reliability, performance, and maintainability. This release reflects a nearly total rewrite of scripts and libraries that support them. >> Command aliases have been added, so that use of the dash in dv-xxx commands is optional. >> dv-shelve is temporarily unavailable. In order to shelve a file, add its name to a .unimportant file in the source area manually. (see below for what is coming) >> dv-import is unavailable in this release. ---- the following are planned, but have been deferred ---- >> dv-shelve has been reimplemented to use attic directories rather than the underlying BCS .unimportant capability. Shelved files are thus accessible via symbolic tag specification in dv-list, dv-tag, and dv-export. Localdev commands recognize the presence of shelved files and directories. Configuration options can be used to automatically shelve files or directories being moved or deleted. >> An updated dv-import is easier to use. >> New script dv-export supports exporting a tagged set of revisions >> CM capabilities will be better integrated into localdev. A CM build area will look much like a localdev build area, with a few extra configuration settings. ---- longer-range plans ---- >> There is a desire at FSL to support CVS capabilities within localdev -- heavy use of branched development and merging in particular. It is not yet clear what form this will take. PACKAGE DISCLAIMER ============================= This software and its documentation are in the public domain and are furnished "as is." The United States government, its instrumentalities, officers, employees, and agents make no warranty, express or implied, as to its usefulness of the software and documentation for any purpose. They assume no responsibility (1) for the use of the software and documentation; or (2) to provide technical support to users. Permission to use, copy, modify, and distribute this software is hereby granted, provided that the entire disclaimer notice appears in all copies. All modifications to this software must be clearly documented, and are the sole responsibility of the agent makeing the modifications. Is significant modifications or enhancements are made to this software, the FSL Software Policy Manager (softwaremgr@fsl.noaa.gov) should be notified. The above permissions are subject to limitation by the GNU distribution licenses of several packages that are distributed as aggregates within this package. Copies of these packages in their entirety are included within this package. Refer to the README and COPYING files within these packages for details. LOCALDEV PACKAGE DESCRIPTION ============================= The localdev development environment consists of a set of scripts that are used to manage source files within an arbitrary number of related production areas. The environment not only provides baseline-oriented source code control within a particular production area, but also provides a simple means for developers to switch contexts between production areas. Facilities for combining and testing the products of multiple baselines and production areas exist, as do utilities supporting the import of files into production areas and the migration of files between production areas. Localdev has been developed at the Forecast Systems Laboratory in Boulder, Colorado. Although it has been developed for use both internally and by the National Weather Service, it provides generic, configurable capabilities that can easily be used directly by any organization developing software. The package is designed for use in a heterogeneous LAN environment, and relies on publicly available packages (GNU make, RCS, BCS, Perl...) for underlying capabilities. All but Perl are included within this package as aggregates. A full description of requirements, limitations, and installation instructions is provided in the accompanying 'INSTALL.localdev' file. A more complete introduction to the package is provided in the accompanying localdev-tutorial.ps file. A capability that is of particular importance to FSL and the National Weather Service is the ability to easily migrate source files between the localdev environment and an external CM system. The actual scripts that implement this capability are dependent upon a particular CM system, and are hence not included in this generic package. This package does onclude a CM interface library that a set of CM scripts (implemented in Perl) can readily use for this purpose. The primary benefit to use of this package is that all of the diverse operations required to manipulate files in a complex development environment are performed safely and reliably by developer-oriented scripts, rather than through a collection of disparate manual UNIX/RCS/BCS commands. This allows the following characteristics to be associated with all operations: coordination scripts ensure that developers coordinate activities within each production area reliability scripts have built-in safeguards to avoid inappropriate operations efficiency scripts expedite all operations, handling many details automatically simplicity scripts simplify development, making it a more reliable process flexibility scripts facilitate sharing of software and developers among multiple projects The localdev environment provides many useful capabilities to developers working within a particular production area that the underlying UNIX, BCS, and RCS utilities themselves cannot provide. These capabilities improve the efficiency of individual developers, and promote efficient interaction between the members of development groups. They also significantly reduce the amount of time required to maintain software baselines.