diff options
Diffstat (limited to 'ACE/docs/CVS.html')
| -rw-r--r-- | ACE/docs/CVS.html | 889 |
1 files changed, 889 insertions, 0 deletions
diff --git a/ACE/docs/CVS.html b/ACE/docs/CVS.html new file mode 100644 index 00000000000..b986f9dec0a --- /dev/null +++ b/ACE/docs/CVS.html @@ -0,0 +1,889 @@ +<!-- $Id$ --> + +<html> +<head> + <title>CVS Minimal Help</title> + <link rev=made href="mailto:levine@cs.wustl.edu"> +<!-- Changed by: David Levine, 26-Mar-1997 --> +</head> + +<body text = "#000000" + link = "#000fff" + vlink = "#ff0f0f" + bgcolor = "#ffffff"> +<hr><p> +<center> + <h1>CVS Minimal Help</h1> + <h2><a href="mailto:levine@cs.wustl.edu">David L. Levine</a></h2> + <font size=-1> + Last modified Monday, 30-Sep-2002 11:15:16 CDT. + </font> +</center> +<h2> </h2> + +This page contains the minimum (and then some) commands necessary to +access and update <a href="http://www.cs.wustl.edu/~schmidt/ACE.html">ACE</a> +through <a href="file:/project/doc/pkg/cvs/cvs-1.10/doc/cvs.ps">CVS</a> +version control. The intended audience is local ACE developers, so +it's not by any means a general introduction to CVS. And some HTML +links and other references are local only.<p> + +The information here is based on CVS versions 1.9 and 1.10.5 and later.<p> + +Notes to emacs users: the emacs Tools/Version Control (or vc) pulldown +has CVS commands: it's well worth checking out. And, see the +<a href="#Preliminaries">Preliminaries</a> section for a handy +addition to your .emacs file.<p> + +If you'd like to update your CVS workspace remotely, see +<a href="http://www.cs.wustl.edu/~nanbor/">Nanbor Wang</a>'s   +<a href="http://www.cs.wustl.edu/~nanbor/CVSUP/">CVSup</a>  page.<p> + +Please <a href="mailto:levine@cs.wustl.edu">email me</a> any corrections or +suggestions!<p> + + +<font size="+2"><strong>Contents:</strong></font> +<ol> + <li><a href="#The Model">The Model</a> + <li><a href="#Preliminaries">Preliminaries</a> + <li><a href="#Getting started with ACE on CVS">Getting + started with ACE on CVS</a> + <li><a href="#Windows NT setup">Windows NT setup</a> + <li><a href="#Checking in changes">Checking in changes</a> + <li><a href="#Workspace update">Workspace update</a> + <li><a href="#Adding/removing files/directories">Adding/removing + files/directories</a> + <li><a href="#Modules">Modules</a> + <li><a href="#ChangeLog updates">ChangeLog updates</a> + <li><a href="#File revisions">File revisions</a> + <li><a href="#File reversion">File reversion</a> + <li><a href="#Renaming a file">Renaming a file</a> + <li><a href="#Local version control">Local version control</a> + <li><a href="#Branches">Branches</a> + <li><a href="#Remote repositories">Remote repositories</a> + <li><a href="#Exporting from CVS">Exporting from CVS</a> + <li><a href="#ACE_wrappers-frozen workspace">ACE_wrappers-frozen + workspace</a> + <li><a href="#ACE release bug-fix branch">ACE release bug-fix branch</a> + <li><a href="#Warning messages/problems">Warning messages/problems</a> + <li><a href="#For more info on CVS">For more info on CVS</a> +</ol> + + +<hr><p> +<h3>1. <a name="The Model">The Model</a></h3> +The following terms are used in the discussion in this web page:<br> +<ul> + <li><em>Repository</em>: The master store of all versions of all + controlled files.<p> + <li><em>Workspace</em>: A user's collection of controlled files. + The user may modify these files at will.<p> + <li><em>Check out</em>: Retrieve one or more files from the + repository, and place them in a workspace. Any version of any + file may be retrieved; typically, that will be the latest version.<p> + <li><em>Check in, or commit</em>: Update the latest version of + one or more files in the repository. This is done from a workspace.<p> + <li><em>Module</em>: Directory. +</ul> + +Our use of CVS fits into the +<a href="http://www.cs.wustl.edu/~levine/ACE_wrappers/docs/ACE-development-process.html">ACE development process</a>.<p> + + +<hr><p> +<h3>2. <a name="Preliminaries">Preliminaries</a></h3> +<p>The <code>CVSROOT</code> environment variable listed below is <font +color=red> <strong><blink>required</blink></strong></font>. If you +want to use CVS from within emacs, you'll have to restart it from a +shell that has <code>CVSROOT</code> defined.<p> + +Emacs users might want to add <var>(setq vc-follow-symlinks t)</var> +to your .emacs file to instruct emacs to follow symlinks to +version-controlled plain files.<p> + +For lack of a better place to put the following, I'll put it here. +It's a good idea to insert a CVS/RCS keyword string at the top of +every file that you place under CVS control. This includes source +files, Makefiles, config files, <em>etc</em>. It will embed in the +file a concise record of the filename, last update time, revision +number, and last user who updated it. For C++ files, the keyword +string is: + <pre> + // $<!-- -->Id$ + </pre> +It's not necessary to fill in the fields of the keyword string, +or modify them when you edit a file that already has one. CVS +does that automatically when you checkout or update the file.<p> + +On Unix systems, you might want to create a file called <code>.cvsrc</code> +in your home directory with the following contents: +<pre><code> +co -P +update -P +</code></pre> +That will cause CVS to prune empty directories on checkout or update. +<p> + + +<hr><p> +<h3>3. <a name="Getting started with ACE on CVS">Getting started with ACE on CVS</a></h3> +Note: the first three steps are for UNIX platforms. See the +<a href="#Windows NT setup">Windows NT setup</a> section for +setup information for Windows NT. +<ol> + <li>% <code>setenv CVSROOT /project/cvs-repository </code> #### + site-specific location<p> + <li>cd to the directory that you want your ACE_wrappers workspace + to be under.<p> + <li>% <code>setenv ACE_ROOT `pwd` </code> #### to set the ACE_ROOT + environment<p> + <li>Change your umask to something like 022 <strong>if</strong> you want + others to be able to view your workspace.<p> + <li>% <code>cvs checkout ACE_wrappers</code><p> + <li>Add the ace/config.h and include/makeinclude/platform_macros.GNU + symlinks. For example, for Sun C++ on SunOS 5.5: + <pre><code> + % ln -s config-sunos5.5.h ace/config.h + % ln -s platform_sunos5_sunc++.GNU include/makeinclude/platform_macros.GNU + </code></pre><p> + <li>Hack away in your own workspace. All files have user write + permission. +</ol><p> + + +<hr><p> +<h3>4. <a name="Windows NT setup">Windows NT setup</a></h3> +Thanks to <a href="http://www.cs.wustl.edu/~brunsch/">Darrell Brunsch</a> +and <a href="http://www.cs.wustl.edu/~irfan/">Irfan Pyarali</a> for +providing this NT setup information. (It contains a site-specific +<code>CVSROOT</code>.)<p> + +You can use the CVS client under Windows NT to keep a local repository +of ACE. To set it up, follow these steps:<P> +<ol> + <li>Find or create a directory in your path (I just created a utils + directory and added it to my path).<p> + <li>Download the files cvs.exe, patch.exe, and win32gnu.dll. They're + in a zip file on + <a href="http://download.cyclic.com/pub/cvs-1.10.5/windows/">Cyclic + Software's download site.</a> (Cyclic Software hsa been acquired + by SourceGear Corporation.)<p> + + Alternatively, <a href="http://www.wincvs.org">WinCVS</a> provides + a graphical front-end on Windows. <strong>NOTE: </strong>if + you use WinCVS, beware that it enables read-only checkout by + default. So be sure not to check out that way if you want to + edit files.<p> + + Thanks to <a href="http://www.riverace.com">Steve Huston</a> for that + note.<p> + <li>Be sure that the <a href="http://www.sourcegear.com/CVS">SourceGear</a> + cvs utilities precede any + <a href="http://www.cygnus.com/misc/gnu-win32/">Cygnus + GNU-Win32 utilities</a> in your path, something like this:<p> + + <pre> + d:\utilities\cvs;D:\utilities\gnuwin32\b18\H-i386-cygwin32\bin + </pre> + <li>Add to your environment: <BR> + <code>LOGNAME = </code><em>username</em><br> + <code>CVSROOT = ace.cs.wustl.edu:/project/cvs-repository</code><br> +</ol> +Please note that this approach uses a remote shell. So, your +account must be able to rsh to the server machine.<p> + +For an alternative approach that uses CVS pserver instead of rsh, +please see Darrell's <a +href="http://tao.cs.wustl.edu/howto/use_win32_pserver.html">CVS +pserver page for Win32</a>.<p> + + +<hr><p> +<h3>5. <a name="Checking in changes">Checking in changes</a></h3> +By convention, any repository change should be documented in +an appropriate ChangeLog. The ChangeLog entry should start with +a line of this form: +<pre> + ChangeLogTag: <em>date</em> <em>name</em> <<em>email address</em>> +</pre><p> + +In all examples below, <code>ChangeLog</code> refers to appropriate +ChangeLog.<p> + +<h4>5.1. Command line</h4> + To enter your workspace changes into the master repository from + the command line::<p> +<pre> + % cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog +</pre><p> + +<h4>5.2. From emacs</h4> + To checkin one file or directory to the repository:<p> +<ol> + <li><code>C-x v v </code>(vc-next-action) to check the file or directory + in<p> + <li>Insert the ChangeLogTag, using the first line of your ChangeLog entry<p> + <li><code>C-c C-c </code> to finish checkin +</ol><p> + + +<hr><p> +<h3>6. <a name="Workspace update">Workspace update</a></h3> +To update your workspace from the master repository, to pick up changes +by others:<p> + <blockquote>% <code>cvs update ACE_wrappers</code></blockquote><p> + +cvs will print out a line for each directory that it enters +(by default, it will recurse through the directory tree; to +disable this and only update one directory, add <code>-l</code> +after <code>update</code>).<p> + +cvs will print out a line for each file that differs from what is +in the repository. This first character indicates the file status: +<ul> + <li><code>U</code> the file was brought <strong>up-to-date</strong>, so + now it agrees with what is in the repository + <li><code>P</code> same as <code>U</code>, except used by CVS server + when it sends a patch instead of the entire file + <li><code>M</code> the file is <strong>modified</strong> in your + workspace with respect to the repository; without any + other message, it means that the file was not modified + by this update operation. If changes were + successfully merged (without conflict), then cvs will + note on the previous lines. + <li><code>C</code> the file needs to be updated, but a + <strong>conflict</strong> was detected. The file now + contains the differences, demarcated with + <code><<<<<<<</code> and + <code>>>>>>>></code>. The + unmodified file was moved to <em>.#file.revision</em>. + You'll need to edit the file to resolve the + differences. I get a lot of false positives on files + that I know I didn't modify locally: for those cases, + I just remove the file and rerun update. + <li><code>A</code> or <code>R</code> The file has been + <strong>added</strong> or <strong>removed</strong> + to/from your workspace, but the add or + remove has not yet been committed. + <li><code>?</code> the file is <strong>private</strong> to your + workspace: it does not exist in the repository +</ul> + +To show what update would do to the currently directory (recursively), +without actually doing it: +<blockquote>% <code>cvs -n update <strong>.</strong></code></blockquote> +<blockquote> + The -q option to update suppresses the ``Updating'' message for each + directory: + <blockquote>% + <code>cvs -nq update <strong>.</strong></code></blockquote> +</blockquote> + +To get the status of the current directory (recursively) with respect to +the repository: +<blockquote>% <code>cvs status <strong>.</strong></code></blockquote> + +To get the status of a single file with respect to the repository, +with symbolic tags displayed: +<blockquote>% <code>cvs status -v <em>file</em></code></blockquote> + +To show local (in current workspace) changes to one or more files, +relative to the versions that they were checked out from: +<blockquote>% <code>cvs diff <em>file(s)/directori(es)</em></code> +</blockquote> + +To show local (in current workspace) changes to one or more files, +relative to the latest versions in the repository: +<blockquote>% <code>cvs diff -rHEAD <em>file(s)/directori(es)</em></code> +</blockquote><p> + + +<hr><p> +<h3>7. <a name="Adding/removing files/directories">Adding/removing files/directories</a></h3> +Adding one or more text files requires two steps: +<pre> + % cvs add <em>file . . .</em> + % cvs commit <em>file . . .</em> +</pre><br> +The commit may be done later, on the entire directory, etc. +Note that cvs <strong>add</strong> is not recursive, so +that the files in each directory of a hierarchy must be +added in separate commands. Also, only files in the current +directory can be added.<p> + +Binary files require the <code>-kb</code> option to <code>cvs add</code>: +<pre> + % cvs add -kb <em>file . . .</em> + % cvs commit <em>file . . .</em> +</pre><br> +If not applied during the <code>add</code> operation, <code>-kb</code> +can be applied using <code>cvs admin -kb</code>.<p> + +Removing files is similar, except the cvs <strong>remove</strong> +command is used instead of the <strong>add</strong> command: +<pre> + % cvs remove <em>file . . .</em> + % cvs commit <em>file . . .</em> +</pre><p> + +An add of an empty directory doesn't require a commit.<p> + +Removing a directory is more problematic. There is no CVS command to +remove (or rename) a directory: it has to be done behind CVS' back, +directly in the repository. This is by design; a CVS command can't be +used to irrevocably destroy information. Therefore, never remove a +directory. You can safely remove all of the files in it, using the +above steps. + +To just remove a directory from a workspace (without removing it from +the repository): first, remove the directory and all of its files +using usual OS commands. Second, run +<pre> + % cvs update -P <em>directory-path </em> +</pre><br> +to prune the directory from the workspace.<p> + + +<hr><p> +<h3>8. <a name="Modules">Modules</a></h3> +Instead of referring to ``ACE_wrappers'' above, you can refer +to a module, such as ace, tests, performance-tests, and so on. +To get a list of known modules, use the -c option to checkout: +<blockquote>% <code>cvs checkout -c</code></blockquote><p> + +<strong>IMPORTANT</strong>: if a subdirectory is added to ACE, it +<strong>must</strong> be added to the list of known modules in +<code>$CVSROOT/CVSROOT/modules</code>! If you don't want to edit that +file, please tell <a href="mailto:levine@cs.wustl.edu">David</a>. The +<code>CVSROOT</code> files are under RCS control. emacs' VC tools +handle them the same way that they handle CVS-controlled files. So, +you can check them out and back in with <code>C-x v v</code>.<p> + +To add an entirely new module: +<ol> + <li>Create the directories/files.<p> + <li>Add the module to <code>$CVSROOT/CVSROOT/modules</code>, as + mentioned above.<p> + <li>Create a new directory in <code>$CVSROOT</code>, owned by the appropriate + group and with sufficient (probably group write+setuid) permissions.<p> + <li>Change to the directory just above the top-level directory for + the module in your workspace.<p> + <li><code>cvs checkout <em>new module name</em></code><p> + <li>Add all of the new directories/files in the module, as described + <a href="#Adding/removing files/directories">above</a>, then commit. +</ol> + + +<hr><p> +<h3>9. <a name="ChangeLog updates">ChangeLog updates</a></h3> +To automatically update the ChangeLog, use the emacs command: +<pre> + C-u C-x v a +</pre> +Thanks to James Hu <jxh@cs.wustl.edu> for this useful tidbit.<p> + +To set a specific host address in your ChangeLog entries, add a line +like this to your <code>~/.emacs</code>: +<pre> + (setq mail-host-address "cs.wustl.edu") +</pre><p> + +To set a specific name in your ChangeLog entries, add a line like +this to your <code>~/.emacs</code>: +<pre> + (setq user-full-name "my full name") +</pre> +Otherwise, CVS uses the name (GECOS field) from your passwd entry.<p> + + +<hr><p> +<h3>10. <a name="File revisions">File revisions</a></h3> +File revisions in and below the current directory may be tagged with: +<pre> + % cvs tag <em>tag</em> <strong>.</strong> +</pre><p> + +To retrieve an old revision of a file, use the -r option to cvs +<strong>update</strong>: +<pre> + % cvs update -r<em>tag file</em> +</pre> +The revision tags of a file can be viewed +with the cvs <strong>log</strong> command.<p> + +Or, to retrieve the file and/or directory versions as of a +certain date and time, use the -D option to cvs <strong>update</strong>, +for example: +<pre> + % cvs update -D "last Saturday" OS.{h,i,cpp} +</pre> + +<strong>NOTE: </strong>The -r and -D options are ``sticky''; they will +apply to the file(s)/directories until overwritten with another revision +tag or date, or until disabled. +They are disabled by using the update -A option, which also checks out +the latest revision: +<pre> + % cvs update -A <em>file</em> +</pre><p> + +To change the log message for a particular revision of a file:<p> +<pre> + % cvs admin -m<em>revision</em>:"<em>new message</em>" <em>file</em> +</pre><p> + + +<hr><p> +<h3>11. <a name="File reversion">File reversion</a></h3> +There are a few ways to revert a file to the last revision that is in +the repository, if you want to abandon your changes to it: + +<ul> + <li>The easiest way to abandon your changes <strong>in your + workspace</strong> is to use the emacs command <code>C-x v u </code> + (vc-revert-buffer). Or from the shell, you could remove the + file and update it with <code>cvs update <em>file</em></code>.<p> + + <li><strong>Do not remove a revision from the cvs repository + directly.</strong> To revert a revision that you made, use the + following command to revert the change in your workspace and + check in the reverted version: +<pre> + % cvs update -j<em>after_change</em> -j<em>before_change</em> <em>file</em> +</pre> + For example, if the version containing the version you want to + revert is 4.10, then, <em>after_change</em> should be + <code>4.10</code> and <em>before_change</em> should be + <code>4.9</code>.<p> + + <strong>NOTE:</strong> this doesn't seem to work with CVS version 1.10.<p> + + Make sure the patch succeeded (if you are not reverting a change + you made long time ago, most likely it will succeed) before + checking in the reverted version.<p> + + Also make sure the you add a ChangeLog entry explaining why + you reverted the change. +</ul> + +<hr><p> +<h3>12. <a name="Renaming a file">Renaming a file</a></h3> +There are three ways to rename a CVS-controlled file. The first +preserves the revision log, but it must be accessed by either the +original or new name, depending on what you want to see. And +revision numbers will start over at 1.0 unless set with the +<code>-r</code> option. It's all done in the user's workspace: +<pre> + Add ChangeLog entry containing: + Renamed <em>OLD</em> to <em>NEW</em> + % mv <em>OLD</em> <em>NEW</em> + % cvs remove <em>OLD</em> + % cvs add <em>NEW</em> + % cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>OLD</em> <em>NEW</em> ChangeLog +</pre><br> + +The second method maintains the revision log in one place and the +revision number sequence. It makes fetching old releases of the +module more difficult, which may be an advantage or disadvantage +depending on local circumstances. It is more dangerous because the +repository is modified directly; see the warning in the cvs info page +about other users accessing the history file while it is being moved: +<pre> + % cd $CVSROOT/<em>MODULE</em> + % mv <em>OLD</em>,v <em>NEW</em>,v +</pre><br> + +The third method is to copy the history file in the repository. +Instead of moving the history file, as in the second method above, +copy it. It's not necessary to prevent others from accessing the +file. The cvs info pages show other steps, to remove the old tags +from the new history file. While technically correct, I don't think +that's necessary for our purposes.<p> + +While the first method is the safest, it has the distinct disadvantage +of hindering access of old versions. If that's not a problem for a +particular file, then it is the preferred approach. As Carlos would +probably say if you asked him, ``it's the right thing to do.''<p> + +If easy access to old versions is desired, I would use the third +approach: copy the history file in the repository.<p> + + +<hr><p> +<h3>13. <a name="Local version control">Local version control</a></h3> +All version control with CVS is done through the master repository. +CVS doesn't provide any facility for local checkpoints. If you want +local version control in your workspace, there's nothing to stop you +from using RCS or SCCS locally (but it might confuse emacs' version +control). The preferred approach is to create a branch, and +checkpoint as much as you want on that branch. When the time comes to +make the changes public, just merge the branch. See the <a +href="#Branches">Branches</a> section of this page, and the cvs man +page, for instructions on creating and using a branch.<p> + + +<hr><p> +<h3>14. <a name="Branches">Branches</a></h3> +To create a branch, you must first create a tag to identify the +branch. Then, you can checkout on that branch. There are various +ways to go about doing this, but these steps show how when starting +from scratch: + +<pre> + % cvs rtag -b <em>branch_tag</em> <em>module(s)</em> + % cvs checkout -r <em>branch_tag</em> <em>module(s)</em> +</pre> + +It's not necessary to checkout all the files in a directory or module +on the branch, but it's probably the easiest and least confusing +approach in the long run. <strong>Note</strong> that it's usually +tricky to tag individual files on a branch because CVS won't +be able to identify which module they're in. By way of example, +to checkout just <code>ace/OS.h</code> on a branch, you'd have to do +this, assuming that you're already in the <code>ace</code> directory: +<pre> + % cd .. + % cvs rtag -b <em>branch_tag</em> ace/OS.h + % cvs checkout -r <em>branch_tag</em> ace/OS.h + % cd ace +</pre> +This can be done after modifying files, and CVS will retain your +modifications. However, if you don't trust CVS, it's best to backup +your files first.<p> + +Checkouts on a branch are sticky, and will apply until the head +version of the file(s) have been checked out with the <code>-A</code> +option to <code>cvs update</code>. Presumably, this will be done +after merging the branch to the main trunk. See the +<a href="#Old file revisions">Old file revisions</a> section of this +page for similar discussion of sticky tags.<p> + +To merge an entire branch to the main trunk, use the <code>-j</code> +(for <em>join</em>) option to <code>cvs checkout</code>. That just +merges in your workspace; the repository can then be updated from the +workspace using <code>commit</code> as usual: +<pre> + Add ChangeLog entry containing: + merged <em>branch_tag</em> + % cvs checkout -P -Aj <em>branch_tag</em> <em>file(s)/directori(es)</em> + % cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog +</pre> +(The <code>-A</code> is needed if you are in the workspace that has +the checkouts on the branch. It updates the workspace to the latest +versions on the main trunk. So, <strong>don't</strong> use it if +you want to keep working on the branch.)<p> + +To merge any changes on the main trunk to a branch, the first time: +<pre> + Add ChangeLog entry containing: + merged main trunk changes + % cvs update -jHEAD <em>file(s)/directori(es)</em> + % cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog + % cvs tag <em>merged_foo_branch</em> <em>file(s)/directori(es)</em> +</pre> + +<strong>AFTER MERGING, APPLY A LABEL TO THE SOURCE BRANCH, +as shown above.</strong> +For example, if you merged from the main trunk to a branch, +apply a new label to the main trunk. You can use that label +later to merge any subsequent changes on the main trunk. The +<code>cvs</code> info pages have a good example of this. +Briefly: + +<pre> + Add ChangeLog entry containing: + merged main trunk changes + % cvs update -j<em>merged_foo_branch</em> -jHEAD <em>file(s)/directori(es)</em> + % cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file(s)/directori(es)</em> ChangeLog + % cvs tag <em>merged_foo_branch_again</em> <em>file(s)/directori(es)</em> +</pre> + + +Note that any files created on the branch won't be visible on +the main trunk, even after the merge. I'm not sure of right +way to take care of this, but I follow these steps for each +file created on the branch:<p> +<ol> + <li>In the repository, move the RCS file from the <var>Attic</var> + directory up to its parent directory. + <li>Edit the RCS file, replacing the "dead" state with "Exp". + <li>Merge from the branch to the main trunk: + <pre> + Add ChangeLog entry containing: + merged <em>branch_tag</em> + % cvs update -Aj <em>branch_tag</em> <em>file</em> + % cvs commit -m "ChangeLogTag: `head -1 ChangeLog`" <em>file</em> ChangeLog + </pre> +</ol> + +To create a file on a branch, in a directory that has not been +checked out on the branch: +<ol> + <li>Add the file and commit it to the main branch + <li>Create the branch tag on the file, and check the file out + on the branch. + <li>Remove the file, cvs remove the file, and commit the removal. + <li>Check the file out on the branch. +</ol> +Alternatively, the recommended procedure is to simply check the +entire directory out on the branch, then create the file.<p> + +In general, deleting branch tags is not recommended. But it's often +necessary, especially when getting started with branches. The +<code>-d</code> option to <code>cvs rtag</code> can be used to delete +a branch tag.<p> + +The use of a branch for maintaining a release is illustrated +in the section on the <a href="#ACE release bug-fix branch">ACE +release bug-fix branch</a>.<p> + + +<hr><p> +<h3>15. <a name="Remote repositories">Remote repositories</a></h3> +Before setting up a repository for remote access, be sure to see +the <a href="file:/project/doc/pkg/cvs/cvs-1.10/doc/cvs.ps">CVS +documentation</a>. There are important security considerations.<p> + +An easy way to access a remote repository is via rsh. These steps +ought to get you going: +<ol> + <li>Install cvs on the local system, if it doesn't already have it.<p> + <li>Add yourself to an <code>.rhosts</code> file on the remote machine + of a user that can access the repository.<p> + <li>Set your <code>CVSROOT</code> environment variable to:<br> + <pre> + <em>remote user</em>@<em>remote host</em>:<em>remote repository</em> + </pre> +</ol> +Then, you can issue cvs commands just as you would on the remote machine.<p> + +If you have ssh on your client machine, you can use ssh instead of +rsh. Just set your <code>CVS_RSH</code> environment variable to +<code>ssh</code>. You don't need to add an <code>.rhosts</code> +entry with ssh, so it's the best alternative for remote repository +access.<p> + +Another way to access to remote cvs repository is to run cvs in +client-server mode. To use this feature, first check if you have your +<code>HOME</code> environment variable set properly. Then, set your +<code>CVSROOT</code> to:<p> +<pre> + :pserver:your_user_id@ace.cs.wustl.edu:/project/cvs-repository +</pre><p> +Then, do a cvs login as +<pre> + % cvs login +</pre><p> +Type in your password when CVS prompts you to enter your password. +This will create a file call "<code>.cvspass</code>" in your home +directory (as defined by <code>$HOME</code>) that contains the +encripted password for the server. You can now perform regular CVS +operation directly.<p> + +<strong>Notice:</strong> It's not difficult to decode the passwords in +<code>.cvspass</code> file. Therefore, never use cvs in client-server +mode in a unsafe environment. (Where others can read your .cvspass +file.)<p> + +To speed up client-server mode operations, it might help to use +the <code>cvs</code> <code>-z</code> option. It requires that +<code>gzip</code> be on your search path on both the client and +server. An example use is:<p> +<pre> + % cvs -z 1 update +</pre><p> + +Thanks to <a href="http://www.cs.wustl.edu/~nanbor/">Nanbor Wang</a> +and <a href="http://www.cs.wustl.edu/~brunsch/">Darrell Brunsch</a> +for figuring out and providing this documentation for cvs +client-server mode.<p> + + +<hr><p> +<h3>16. <a name="Exporting from CVS">Exporting from CVS</a></h3> +There are two different strategies for exporting CVS-controlled files, +such as for code releases. The first, preferred approach is to use +the cvs <strong>export</strong> command to stage a version of the +controlled files to a non-controlled directory. This version will +not have any of the CVS files in it. THe second approach is to +create a release from a user's CVS-controlled workspace.<p> + +To use cvs <strong>export</strong>, either a date or revision +tag must be specified. It's usually a good idea to tag the sources +with a revision tag and use that. So, the steps would be:<br> +<pre> + % cd <em>root of directory tree</em> + % cvs tag <em>tag</em> <strong>.</strong> + % cd <em>staging directory</em> + % cvs export -r <em>tag</em> + % find . -print | cpio -o -H tar | gzip -9 > <em>tar filename</em> +</pre> + +To tag and create a release in the form of a gzip'ped tar file +from a user's workspace: +<pre> + % cd <em>root of directory tree</em> + % cvs tag <em>tag</em> <strong>.</strong> + % find . -name CVS -prune -o -print | cpio -o -H tar | gzip -9 > <em>tar filename</em> +</pre> + +The relative advantage of the first, export approach is that you will +be sure that only CVS-controlled files will be released. However, it +requires the extra step and creation of the staging area.<p> + +This extra step is one reason why we don't currently stage releases of +ACE. Instead, they are built from Doug's personal workspace. That +workspace is visible on the web, so that ACE users can track the very +latest changes without any explicit action by Doug. If we were to +stage it, to make any change visible would require an explicit move to +the staging area.<p> + + +<hr><p> +<h3>17. <a name="ACE_wrappers-frozen workspace">ACE_wrappers-frozen workspace</a></h3> + +This section applies to the DOC group at Wash. U. only:<p> + +There's now a ``frozen'' ACE in +<strong>/project/cvs-repository/ACE_wrappers-frozen/</strong>. +It contains the latest official release of ACE.<p> + +There are complete g++ 2.7.2.1 and Sun C++ 4.2 builds in the +<strong>build</strong> directory below the directory noted above. +To use one of these builds, set or prepend to these environment variables:<p> +<table border> +<tr> +<th>Compiler</th> +<th>set <strong>WRAPPER_ROOT</strong> to:</th> +<th>prepend to <strong>LD_LIBRARY_PATH</strong>:</th> +<tr> +<td>g++</td> +<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_g++</td> +<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_g++/ace</td> +<tr> +<td>Sun C++</td> +<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_sunc++-4.2</td> +<td>/project/cvs-repository/ACE_wrappers-frozen/build/SunOS5_sunc++-4.2/ace</td> +</table><p> + + +<hr><p> +<h3>18. <a name="ACE release bug-fix branch">ACE release bug-fix branch</a></h3> + +This section applies to the DOC group at Wash. U. only:<p> + +The ``main line'' CVS branch will (continue to) be the ``new features'' +branch. If you want the very latest and greatest ACE at all times, no +changes to the use of your workspace are required. Just +<code>cvs update</code> it as usual.<p> + +Bug fixes to the official release will go on a branch. For the ACE +4.2 release, for example, this branch is name +<strong>ACE-4_2</strong>. (CVS does not allow periods in branch names +or any other tags.) To use it, do this in your workspace: +<pre> + % cd .. + % cvs checkout -r ACE-4_2 ACE_wrappers +</pre> + +From that point on, all updates and commits in that workspace +will be from/to the <strong>ACE-4_2</strong> branch.<p> + + +<hr><p> +<h3>19. <a name="Warning messages/problems">Warning messages/problems</a></h3> +<dl> +<blockquote> + + <dt><pre>cvs update: conflict: <em>foo </em>is modified but no longer in the repository<br> +U <em>bar</em></pre> + <dd>That might indicate that file <em>foo</em> was renamed to <em>bar</em>. + If so, <em>foo</em> should be removed from the current workspace. (And + that warning will not reoccur for the workspace, because its CVS will + have removed <em>foo</em> from the workspace entries and checked out + <em>bar</em>.)<p> + + <dt><pre>cvs update: [<em>time</em>] waiting for <em>user</em>'s lock in <em>repository</em></pre> + <dd>Check for lock files and directories in the <code>$CVSROOT/CVSROOT</code> + and lock files anywhere in the <code>$CVSROOT</code> hierarchy. Remove + ones that no longer appear to be in use and retry. Lock files and + directories have names starting with ``.#'', I think.<p> + + <dt>Why does a file in the repository not have group and/or other read + permission?<p> + <dd>Because it didn't have those permissions when it was added to the + repository. To fix it, those permissions can be added to the ,v file in + the repository. To avoid it, those permissions should be added to the + file before it is created/committed the first time.<p> + + <dt>Why does CVS keep removing group/and or other read permission from a + file in my workspace?<p> + <dd>Because your umask is something like 7 or 77. Change it to something + like 22. If you don't want to change it for everything, then alias cvs; + in t/csh:<br> + <blockquote>% <code>alias cvs '(umask 22; \cvs \!*)'</code></blockquote> + <p> + Also, the file will have to have mode 644 before you commit it. So if + your editor removes group/other read permission, you'll have to ``fix'' + that as well.<p> + + <dt>I modified Makefile in my workspace so I don't build static or shared + ACE libraries. But, I forgot about it and commited the modified + Makefile to the repository. Help?<p> + <dd>You'll have to correct the Makefile and commit your corrections.<p> + + Instead of modifying your makefile, try these commands to build the + ACE static and shared libraries, respectively: + <blockquote>% make <code>static_libs_only=1</code></blockquote> + + <blockquote>% make <code>shared_libs_only=1</code></blockquote> + +</blockquote> +</dl><p> + + +<hr><p> +<h3>20. <a name="For more info on CVS">For more info on CVS</a></h3> +Please see these sources for more information on CVS: +<ul> + <li>David Discher's <a href="http://dpd.dpdtech.com/cvs/">Quick N + Dirty CVS HOW-TO</a> is really helpful.<p> + + <li>Please check out David G. Grubbs' great, comprehensive <a + href="http://cellworks.washington.edu/pub/docs/cvs/cvs-FAQ/cvsfaq0.html">"The + CVS FAQ"</a>.<p> + + <li><a href="http://www.loria.fr/~molli/cvs-index.html">CVS Bubbles</a> + is a collection of useful CVS information and links.<p> + + <li>Commercial support for CVS is available from <a + href="http://www.sourcegear.com/CVS">SourceGear Corporation</a>. + Their web pages are very helpful.<p> + + <li>Terris Linenbach has an interesting, brief discussion of + source code management on-line at <a + href="http://devguy.com/fp/ProgrammersCanvas">Programmers' + Canvas</a>. Programmers' Canvas is a pattern language, + also quite interesting. +</ul> + +<p><hr> +<p>Back to +<a href="http://www.cs.wustl.edu/~levine">David L. Levine's home page</a>. +<p> + + + +<font size=-1> +Last modified 11:15:16 CDT 30 September 2002. +<br> +[an error occurred while processing this directive] +[an error occurred while processing this directive] +<p> +</font> + + + +</body> +</html> |