mirror of
https://github.com/nwchemgit/nwchem.git
synced 2026-07-21 06:25:21 -04:00
RJH: new SCF directive and some CVS info
This commit is contained in:
Robert Harrison
parent
45c59fe435
commit
7fa3272459
2 changed files with 564 additions and 1 deletions
|
|
@ -1,4 +1,5 @@
|
|||
.SUFFIXES: .tex .dvi .ps .log .aux
|
||||
.SUFFIXES:
|
||||
.SUFFIXES: .ps .dvi .aux .log .tex
|
||||
|
||||
PSFLAGS = -D 300
|
||||
|
||||
|
|
|
|||
562
doc/cvshelp.man
Normal file
562
doc/cvshelp.man
Normal file
|
|
@ -0,0 +1,562 @@
|
|||
.\" cvshelp.man,v 1.1 1992/04/10 03:04:21 berliner Exp
|
||||
.\" Contributed by Lowell Skoog <fluke!lowell@uunet.uu.net>
|
||||
.\" Full space in nroff; half space in troff
|
||||
.de SP
|
||||
.if n .sp
|
||||
.if t .sp .5
|
||||
..
|
||||
.\" Start a command example
|
||||
.de XS
|
||||
.SP
|
||||
.in +.5i
|
||||
.ft B
|
||||
.nf
|
||||
..
|
||||
.\" End a command example
|
||||
.de XE
|
||||
.fi
|
||||
.ft P
|
||||
.in -.5i
|
||||
.SP
|
||||
..
|
||||
.TH CVSHELP LOCAL "17 March 1991" FLUKE
|
||||
.SH NAME
|
||||
cvshelp \- advice on using the Concurrent Versions System
|
||||
.SH DESCRIPTION
|
||||
This man page is based on experience using CVS.
|
||||
It is bound to change as we gain more experience.
|
||||
If you come up with better advice than is found here,
|
||||
contact the Software Technology
|
||||
Group and we will add it to this page.
|
||||
.SS "Getting Started"
|
||||
Use the following steps to prepare to use CVS:
|
||||
.TP
|
||||
\(bu
|
||||
Take a look at the CVS manual page to see what it can do for you, and
|
||||
if it fits your environment (or can possibly be made to fit your
|
||||
environment).
|
||||
.XS
|
||||
man cvs
|
||||
.XE
|
||||
If things look good, continue on...
|
||||
.TP
|
||||
\(bu
|
||||
Setup the master source repository. Choose a directory with
|
||||
ample disk space available for source files. This is where the RCS
|
||||
`,v' files will be stored. Say you choose
|
||||
.B /src/master
|
||||
as the root
|
||||
of your source repository. Make the
|
||||
.SB CVSROOT.adm
|
||||
directory in the root of the source repository:
|
||||
.XS
|
||||
mkdir /src/master/CVSROOT.adm
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Populate this directory with the
|
||||
.I loginfo
|
||||
and
|
||||
.I modules
|
||||
files from the
|
||||
.B "/usr/doc/local/cvs"
|
||||
directory. Edit these files to reflect your local source repository
|
||||
environment \- they may be quite small initially, but will grow as
|
||||
sources are added to your source repository. Turn these files into
|
||||
RCS controlled files:
|
||||
.XS
|
||||
cd /src/master/CVSROOT.adm
|
||||
ci \-m'Initial loginfo file' loginfo
|
||||
ci \-m'Initial modules file' modules
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Run the command:
|
||||
.XS
|
||||
mkmodules /src/master/CVSROOT.adm
|
||||
.XE
|
||||
This will build the
|
||||
.BR ndbm (3)
|
||||
file for the modules database.
|
||||
.TP
|
||||
\(bu
|
||||
Remember to edit the
|
||||
.I modules
|
||||
file manually when sources are checked
|
||||
in with
|
||||
.B checkin
|
||||
or CVS
|
||||
.BR add .
|
||||
A copy of the
|
||||
.I modules
|
||||
file for editing can be retrieved with the command:
|
||||
.XS
|
||||
cvs checkout CVSROOT.adm
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Have all users of the CVS system set the
|
||||
.SM CVSROOT
|
||||
environment variable appropriately to reflect the placement of your
|
||||
source repository. If the above example is used, the following
|
||||
commands can be placed in a
|
||||
.I .login
|
||||
or
|
||||
.I .profile
|
||||
file:
|
||||
.XS
|
||||
setenv CVSROOT /src/master
|
||||
.XE
|
||||
for csh users, and
|
||||
.XS
|
||||
CVSROOT=/src/master; export CVSROOT
|
||||
.XE
|
||||
for sh users.
|
||||
.SS "Placing Locally Written Sources Under CVS Control"
|
||||
Say you want to place the `whizbang' sources under
|
||||
CVS control. Say further that the sources have never
|
||||
been under revision control before.
|
||||
.TP
|
||||
\(bu
|
||||
Move the source hierarchy (lock, stock, and barrel)
|
||||
into the master source repository:
|
||||
.XS
|
||||
mv ~/whizbang $CVSROOT
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Clean out unwanted object files:
|
||||
.XS
|
||||
cd $CVSROOT/whizbang
|
||||
make clean
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Turn every file in the hierarchy into an RCS controlled file:
|
||||
.XS
|
||||
descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-nV\fR\fIx\fR\fB_\fR\fIy\fR\fB *'
|
||||
.XE
|
||||
In this example, the initial release tag is \fBV\fIx\fB_\fIy\fR,
|
||||
representing version \fIx\fR.\fIy\fR.
|
||||
.LP
|
||||
You can use CVS on sources that are already under RCS control.
|
||||
The following example shows how.
|
||||
In this example, the source package is called `skunkworks'.
|
||||
.TP
|
||||
\(bu
|
||||
Move the source hierarchy into the master source
|
||||
repository:
|
||||
.XS
|
||||
mv ~/skunkworks $CVSROOT
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Clean out unwanted object files:
|
||||
.XS
|
||||
cd $CVSROOT/skunkworks
|
||||
make clean
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Clean out unwanted working files, leaving only the RCS `,v' files:
|
||||
.XS
|
||||
descend \-r rcsclean
|
||||
.XE
|
||||
Note: If any working files have been checked out and changed,
|
||||
.B rcsclean
|
||||
will fail. Check in the modified working files
|
||||
and run the command again.
|
||||
.TP
|
||||
\(bu
|
||||
Get rid of
|
||||
.SB RCS
|
||||
subdirectories. CVS does not use them.
|
||||
.XS
|
||||
descend \-r \-f 'mv RCS/*,v .'
|
||||
descend \-r \-f 'rmdir RCS'
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Delete any unwanted files that remain in the source hierarchy. Then
|
||||
make sure all files are under RCS control:
|
||||
.XS
|
||||
descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-n\fR\fItag\fR\fB *'
|
||||
.XE
|
||||
.I tag
|
||||
is the latest symbolic revision tag that you applied to your package
|
||||
(if any). Note: This command will probably generate lots of error
|
||||
messages (for directories and existing RCS files) that you can
|
||||
ignore.
|
||||
.SS "Placing a Third-Party Source Distribution Under CVS Control"
|
||||
The
|
||||
.B checkin
|
||||
command checks third-party sources into CVS. The
|
||||
difference between third-party sources and locally
|
||||
written sources is that third-party sources must be checked into a
|
||||
separate branch (called the
|
||||
.IR "vendor branch" )
|
||||
of the RCS tree. This makes it possible to merge local changes to
|
||||
the sources with later releases from the vendor.
|
||||
.TP
|
||||
\(bu
|
||||
Save the original distribution kit somewhere. For example, if the
|
||||
master source repository is
|
||||
.B /src/master
|
||||
the distribution kit could be saved in
|
||||
.BR /src/dist .
|
||||
Organize the distribution directory so that each release
|
||||
is clearly identifiable.
|
||||
.TP
|
||||
\(bu
|
||||
Unpack the package in a scratch directory, for example
|
||||
.BR ~/scratch .
|
||||
.TP
|
||||
\(bu
|
||||
Create a repository for the package.
|
||||
In this example, the package is called `Bugs-R-Us 4.3'.
|
||||
.XS
|
||||
mkdir $CVSROOT/bugs
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Check in the unpacked files:
|
||||
.XS
|
||||
cd ~/scratch
|
||||
checkin \-m 'Bugs-R-Us 4.3 distribution' bugs VENDOR V4_3
|
||||
.XE
|
||||
There is nothing magic about the tag `VENDOR', which is applied to
|
||||
the vendor branch. You can use whatever tag you want. `VENDOR' is a
|
||||
useful convention.
|
||||
.TP
|
||||
\(bu
|
||||
Never modify vendor files before checking them in.
|
||||
Check in the files
|
||||
.I exactly
|
||||
as you unpacked them.
|
||||
If you check in locally modified files, future vendor releases may
|
||||
wipe out your local changes.
|
||||
.SS "Working With CVS-Controlled Sources"
|
||||
To use or edit the sources, you must check out a private copy.
|
||||
For the following examples, the master files are assumed to reside in
|
||||
.BR "$CVSROOT/behemoth" .
|
||||
The working directory is
|
||||
.BR "~/work" .
|
||||
See
|
||||
.BR cvs (local)
|
||||
for more details on the commands mentioned below.
|
||||
.TP
|
||||
.I "To Check Out Working Files
|
||||
Use CVS
|
||||
.BR checkout :
|
||||
.XS
|
||||
cd ~/work
|
||||
cvs checkout behemoth
|
||||
.XE
|
||||
There is nothing magic about the working directory. CVS will check
|
||||
out sources anywhere you like. Once you have a working copy of the
|
||||
sources, you can compile or edit them as desired.
|
||||
.TP
|
||||
.I "To Display Changes You Have Made"
|
||||
Use CVS
|
||||
.BR diff
|
||||
to display detailed changes, equivalent to
|
||||
.BR rcsdiff (local).
|
||||
You can also use
|
||||
.BR cvscheck (local)
|
||||
to list files added, changed, and removed in
|
||||
the directory, but not yet
|
||||
.BR commit ted.
|
||||
You must be in a directory containing working files.
|
||||
.TP
|
||||
.I "To Display Revision Information"
|
||||
Use CVS
|
||||
.BR log ,
|
||||
which is equivalent to
|
||||
.BR rlog (local).
|
||||
You must be in a directory containing working files.
|
||||
.TP
|
||||
.I "To Update Working Files"
|
||||
Use CVS
|
||||
.BR update
|
||||
in a directory containing working files.
|
||||
This command brings your working files up
|
||||
to date with changes checked into the
|
||||
master repository since you last checked out or updated
|
||||
your files.
|
||||
.TP
|
||||
.I "To Check In Your Changes"
|
||||
Use CVS
|
||||
.BR commit
|
||||
in a directory containing working files.
|
||||
This command checks your changes into the master repository.
|
||||
You can specify files by name or use
|
||||
.XS
|
||||
cvs commit \-a
|
||||
.XE
|
||||
to
|
||||
.B commit
|
||||
all the files you have changed.
|
||||
.TP
|
||||
.I "To Add a File"
|
||||
Add the file to the working directory.
|
||||
Use CVS
|
||||
.B add
|
||||
to mark the file as added.
|
||||
Use CVS
|
||||
.B commit
|
||||
to add the file to the master repository.
|
||||
.TP
|
||||
.I "To Remove a File"
|
||||
Remove the file from the working directory.
|
||||
Use CVS
|
||||
.B remove
|
||||
to mark the file as removed.
|
||||
Use CVS
|
||||
.B commit
|
||||
to move the file from its current location in the master repository
|
||||
to the CVS
|
||||
.IR Attic
|
||||
directory.
|
||||
.TP
|
||||
.I "To Add a Directory"
|
||||
Add the directory to the working directory.
|
||||
Use CVS
|
||||
.B add
|
||||
to add the directory to the master repository.
|
||||
.TP
|
||||
.I "To Remove a Directory"
|
||||
.br
|
||||
You shouldn't remove directories under CVS. You should instead remove
|
||||
their contents and then prune them (using the
|
||||
.B \-f
|
||||
and
|
||||
.B \-p
|
||||
options) when you
|
||||
.B checkout
|
||||
or
|
||||
.B update
|
||||
your working files.
|
||||
.TP
|
||||
.I "To Tag a Release"
|
||||
Use CVS
|
||||
.B tag
|
||||
to apply a symbolic tag to the latest revision of each file in the
|
||||
master repository. For example:
|
||||
.XS
|
||||
cvs tag V2_1 behemoth
|
||||
.XE
|
||||
.TP
|
||||
.I "To Retrieve an Exact Copy of a Previous Release"
|
||||
During a CVS
|
||||
.B checkout
|
||||
or
|
||||
.BR update ,
|
||||
use the
|
||||
.B \-r
|
||||
option to retrieve revisions associated with a symbolic tag.
|
||||
Use the
|
||||
.B \-f
|
||||
option to ignore all RCS files that do not contain the
|
||||
tag.
|
||||
Use the
|
||||
.B \-p
|
||||
option to prune directories that wind up empty because none
|
||||
of their files matched the tag. Example:
|
||||
.XS
|
||||
cd ~/work
|
||||
cvs checkout \-r V2_1 \-f \-p behemoth
|
||||
.XE
|
||||
.SS "Logging Changes"
|
||||
It is a good idea to keep a change log together with the
|
||||
sources. As a minimum, the change log should name and describe each
|
||||
tagged release. The change log should also be under CVS control and
|
||||
should be tagged along with the sources.
|
||||
.LP
|
||||
.BR cvslog (local)
|
||||
can help. This command logs
|
||||
changes reported during CVS
|
||||
.B commit
|
||||
operations. It automatically
|
||||
updates a change log file in your working directory. When you are
|
||||
finished making changes, you (optionally) edit the change log file and
|
||||
then commit it to the master repository.
|
||||
.LP
|
||||
Note: You must edit the change log to describe a new release
|
||||
and
|
||||
.B commit
|
||||
it to the master repository
|
||||
.I before
|
||||
.BR tag ging
|
||||
the release using CVS. Otherwise, the release description will not be
|
||||
included in the tagged package.
|
||||
.LP
|
||||
See
|
||||
.BR cvslog (local)
|
||||
for more information.
|
||||
.SS "Merging a Subsequent Third-Party Distribution"
|
||||
The initial steps in this process are identical to placing a
|
||||
third-party distribution under CVS for the first time: save the
|
||||
distribution kit and unpack the package in a scratch directory. From
|
||||
that point the steps diverge.
|
||||
The following example considers release 5.0 of the
|
||||
Bugs-R-Us package.
|
||||
.TP
|
||||
\(bu
|
||||
Check in the sources after unpacking them:
|
||||
.XS
|
||||
cd ~/scratch
|
||||
checkin \-m 'Bugs-R-Us 5.0 distribution' bugs VENDOR V5_0 \\
|
||||
| tee ~/WARNINGS
|
||||
.XE
|
||||
It is important to save the output of
|
||||
.B checkin
|
||||
in a file
|
||||
because it lists the sources that have been locally modified.
|
||||
It is best to save the file in a different directory (for example,
|
||||
your home directory). Otherwise,
|
||||
.B checkin
|
||||
will try to check it into the master repository.
|
||||
.TP
|
||||
\(bu
|
||||
In your usual working directory, check out a fresh copy of the
|
||||
distribution that you just checked in.
|
||||
.XS
|
||||
cd ~/work
|
||||
cvs checkout \-r VENDOR bugs
|
||||
.XE
|
||||
The
|
||||
.B checkout
|
||||
command shown above retrieves the latest revision on the vendor branch.
|
||||
.TP
|
||||
\(bu
|
||||
See the `WARNINGS' file for a list of all locally modified
|
||||
sources.
|
||||
For each locally modified source,
|
||||
look at the differences between
|
||||
the new distribution and the latest local revision:
|
||||
.XS
|
||||
cvs diff \-r \fR\fILocalRev file\fR\fB
|
||||
.XE
|
||||
In this command,
|
||||
.I LocalRev
|
||||
is the latest
|
||||
numeric or symbolic revision
|
||||
on the RCS trunk of
|
||||
.IR file .
|
||||
You can use CVS
|
||||
.B log
|
||||
to get the revision history.
|
||||
.TP
|
||||
\(bu
|
||||
If your local modifications to a file have been incorporated into
|
||||
the vendor's distribution, then you should reset the default RCS
|
||||
branch for that file to the vendor branch. CVS doesn't provide a
|
||||
mechanism to do this. You have to do it by hand in the master
|
||||
repository:
|
||||
.XS
|
||||
rcs \-bVENDOR \fR\fIfile\fR\fB,v
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
If your local modifications need to be merged with the
|
||||
new distribution, use CVS
|
||||
.B join
|
||||
to do it:
|
||||
.XS
|
||||
cvs join \-r VENDOR \fR\fIfile\fR\fB
|
||||
.XE
|
||||
The resulting file will be placed in your working directory.
|
||||
Edit it to resolve any overlaps.
|
||||
.TP
|
||||
\(bu
|
||||
Test the merged package.
|
||||
.TP
|
||||
\(bu
|
||||
Commit all modified files to the repository:
|
||||
.XS
|
||||
cvs commit \-a
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Tag the repository with a new local tag.
|
||||
.SS "Applying Patches to Third-Party Sources"
|
||||
Patches are handled in a manner very similar to complete
|
||||
third-party distributions. This example considers patches applied to
|
||||
Bugs-R-Us release 5.0.
|
||||
.TP
|
||||
\(bu
|
||||
Save the patch files together with the distribution kit
|
||||
to which they apply.
|
||||
The patch file names should clearly indicate the patch
|
||||
level.
|
||||
.TP
|
||||
\(bu
|
||||
In a scratch directory, check out the last `clean' vendor copy \- the
|
||||
highest revision on the vendor branch with
|
||||
.IR "no local changes" :
|
||||
.XS
|
||||
cd ~/scratch
|
||||
cvs checkout \-r VENDOR bugs
|
||||
.XE
|
||||
.TP
|
||||
\(bu
|
||||
Use
|
||||
.BR patch (local)
|
||||
to apply the patches. You should now have an image of the
|
||||
vendor's software just as though you had received a complete,
|
||||
new release.
|
||||
.TP
|
||||
\(bu
|
||||
Proceed with the steps described for merging a subsequent third-party
|
||||
distribution.
|
||||
.TP
|
||||
\(bu
|
||||
Note: When you get to the step that requires you
|
||||
to check out the new distribution after you have
|
||||
checked it into the vendor branch, you should move to a different
|
||||
directory. Do not attempt to
|
||||
.B checkout
|
||||
files in the directory in
|
||||
which you applied the patches. If you do, CVS will try to merge the
|
||||
changes that you made during patching with the version being checked
|
||||
out and things will get very confusing. Instead,
|
||||
go to a different directory (like your working directory) and
|
||||
check out the files there.
|
||||
.SS "Advice to Third-Party Source Hackers"
|
||||
As you can see from the preceding sections, merging local changes
|
||||
into third-party distributions remains difficult, and probably
|
||||
always will. This fact suggests some guidelines:
|
||||
.TP
|
||||
\(bu
|
||||
Minimize local changes.
|
||||
.I Never
|
||||
make stylistic changes.
|
||||
Change makefiles only as much as needed for installation. Avoid
|
||||
overhauling anything. Pray that the vendor does the same.
|
||||
.TP
|
||||
\(bu
|
||||
Avoid renaming files or moving them around.
|
||||
.TP
|
||||
\(bu
|
||||
Put independent, locally written files like help documents, local
|
||||
tools, or man pages in a sub-directory called `local-additions'.
|
||||
Locally written files that are linked into an existing executable
|
||||
should be added right in with the vendor's sources (not in a
|
||||
`local-additions' directory).
|
||||
If, in the future,
|
||||
the vendor distributes something
|
||||
equivalent to your locally written files
|
||||
you can CVS
|
||||
.B remove
|
||||
the files from the `local-additions' directory at that time.
|
||||
.SH SEE ALSO
|
||||
.BR cvs (local),
|
||||
.BR checkin (local),
|
||||
.BR cvslog (local),
|
||||
.BR cvscheck (local)
|
||||
.SH AUTHOR
|
||||
Lowell Skoog
|
||||
.br
|
||||
Software Technology Group
|
||||
.br
|
||||
Technical Computing
|
||||
Loading…
Add table
Add a link
Reference in a new issue