#F>=========================================================================
# INSTALL.localdev
# RCS: $Revision: 1.22 $ $Date: 2000/09/28 18:05:42 $ $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
       (under contract to FSL through Systems Technology Associates)
    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 1.10
------------
This is the only localdev 1.x release that can inter-operate with
localdev 2.x. It is identical to the prior localdev release except for
a small patch enabling inter-operability.

This release of localdev has a complete accompanying nwscm
accessory used to interface with the NWS configuration management system.
While there are a couple of scripts that have not yet been implemented, the
rest have been relatively stable. This release currently provides pre-built
aggregates for HP-UX and for Red Hat Linux on an Intel platform.

The following scripts are included in this release:

Setup Scripts
   dv-config : manage production area configuration 
   dv-help : display general information about localdev scripts 
   dv-scope : set the scope of the localdev environment 
   dv-select : select current localdev context 

Development Scripts
   dv-commit : submit new files or revisions to the current baseline 
   dv-create : create source files from standardized templates 
   dv-expand : intelligently expand tabs 
   dv-list : list information about source files 
   dv-lock : stage and lock files 
   dv-merge : merge revisions in parent and current baselines (***)
   dv-mkstaging : create staging areas 
   dv-mvfile : move files within a baseline 
   dv-path : access localdev-relevant locations 
   dv-revert : unlock and unstage files 
   dv-rmfile : remove baseline files 
   dv-rmstaging : remove a staging area from the current production area 
   dv-shelve : reversibly enable/disable files or directories for current use 
   dv-stage : stage files 
   dv-state : display or set production area or baseline state 
   dv-sync : synchronize your current staging area with its baseline 
   dv-tag : tag revisions of baseline files 
   dv-unstage : unstage files 
   dv-update : update file headings within source files 

   (*** = release delayed, available in localdev 2.x only)

Tool Access Scripts
   dv--cmp : access underlying cmp comparison utility (GNU) 
   dv--diff : access underlying diff comparison utility (GNU) 
   dv--diff3 : access underlying diff3 comparison utility (GNU) 
   dv--make : access underlying make incremental build utility (GNU) 
   dv--patch : access underlying patch utility (GNU) 
   dv--rcs : restricted access to underlying rcs control utility (RCS) 
   dv--ci : restricted access to underlying ci checkin utility (RCS) 
   dv--co : restricted access to underlying co checkout utility (RCS) 
   dv--rcsdiff : access underlying rcsdiff comparison utility (RCS) 
   dv--rlog : access underlying rlog revision control utility (RCS) 

Maintenance Scripts
   dv-import : import baseline directories or external files 
   dv-mkarea : create localdev production areas 
   dv-mkbase : create baselines in the current production area 
   dv-mkdir : create directories within the baseline that is linked
              to the current staging area 
   dv-mvbase : rename a baseline in the current production area 
   dv-mvdir : rename a directory within the baseline that is linked to
              the current staging area 
   dv-repair : repair (or validate) current baseline 
   dv-rmbase : remove baselines from the current production area 
   dv-rmdir : remove directories within the baseline that is linked
              to the current staging area 
   dv-sever : sever locks that others have placed on files 
   dv_block : block direct access to incompatible commands 

Known Problems and Limitations
------------------------------
>> this release does not support merges between production areas
>> this release is dependent on BCS, a package that has been 
   superceded by CVS.
>> localdev scripts will not run under Microsoft operating systems.
>> The CM access library, while functional, does not make a complete 
   interface to an external CM system easy to achieve. Of course, much
   of that depends upon the CM system and the types of scripts being developed.

Significant Changes since Prior Releases
----------------------------------------

Release 1.10
---------------
>> minor changes made to achieve inter-operability with localdev 2.x

Release 1.08
---------------
>> stampPattern documentation updated to encompass multiple, comma-separated
   stamps
>> improved dv-shelve feedback, and fixed a library bug that was making
   dv-shelve fail.
>> fixed a locked/updated state error affecting dv-list.
>> Verified compatibility with newer versions of Perl

Release 1.07
---------------
>> dv-mkstaging and dv-mkarea now prompt for non-default locations.
   If specified, then a symbolic link is created automatically, making the
   area accessible via the default location.
>> The build platform property is no longer defined or used.
>> A few script output messages were altered.

Release 1.06
---------------
>> dv-list now shows authors in revision history
>> dv-sever had been truncating some types of RCS files. It no longer does.
>> libraries were modified to work with nwscm cron initialization logic.
>> scripts were cleaned up to work with 5.004 and 5.005 versions of Perl

Release 1.05
---------------
>> dv_unavail no longer generates a help message when accessed via symlink.

Release 1.04
---------------
>> Internal changes were made to support nwscm accessory 2.05
>> Error handling was made more reliable.
>> Skip messages now appear when in NOOP mode.

Release 1.03
---------------
>> Internal changes were made to support nwscm accessory 2.02
>> Quotes and other special characters are handled when revision messages
   are specified in dv-commit.
>> Failures arising from file ownership problems were eliminated within
   dv-sever, dv-tag, and dv-shelve.
>> The '-a' option has been removed from dv-commit, dv-lock, dv-revert,
   dv-sever, dv-stage, dv-tag, dv-unstage, and dv-update. Use of a '.'
   parameter is equivalent.
>> More immediate feedback has been added to dv-config and dv-repair.
>> Extraneous choices associated with dv-mkstaging's prompt for build
   platform have been eliminated
>> The localdev no longer interferes with use direct use of rcsdiff.
>> dv-import was enhanced to support stamping as does dv-commit.
>> dv-commit now only asks for stamps when needed, and commit checks all
   work as expected.
>> A multi-tasking feature was added to support simultaneous use of multiple
   localdev environment settings
>> dv-rmstaging now properly deselects a removed staging area
>> A quiet option was added to dv-list, dv-sync, dv-upload, dv-download,
   and dv-merge.
>> Some '/bin' file dependencies were removed. Dependencies on '/usr/bin/clear',
   '/usr/bin/file', '/usr/bin/test', and '/usr/bin/wc' remain.
>> dv-commit now expands RCS keywords properly when comparing files.
>> A number of unusual error conditions are now handled gracefully.
>> A bypass option has been added to both dv-mvfile and dv-rmfile.
>> Use of dv--rcs, dv--ci, and dv--co can now be used by developers as well
   as production area owners.
>> Errors in nws-upload and nws-download have been corrected. 
   nws-download was erroneously downloading files. nws-upload was both
   leaving extra tags within local files and associating updates with 
   the set of change documents specified to trigger uploads, rather
   associating those that were appropriate for each file. The new
   version of nws-upload repairs tags in local files.

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.