CWCVS
is a version control plugin for Metrowerks
CodeWarrior which allows you to use WinCVS.org's
public domain MacCVS CVS
client for source control without leaving the CodeWarrior IDE.
CVS is a widely used POSIX-based source control system and CVS clients are
available on many platforms, including the Macintosh, making it a reasonable
choice for multiple platform development. CWCVS allows Macintosh developers
to use CVS with CodeWarrior without arcane command line arguments or scripts.
CVS is not a simple system. We have attempted to make the interface in
CWCVS fairly easy to use and we have automated a couple of gotchas (directory
creation and editing of binary files, for example) but we strongly recommend
reading the CVS documentation
before getting in too deep.
Return to the Contents.
CWCVS provides access to the the standard functions of most source-code control systems:
CWCVS also provides integration with Finder's labeling sytem via the VCSComments Pref panel.
Return to the Contents.
CWCVS requires a version of the CodeWarrior IDE that supports the VCS plugin
architecture. This means version 1.7.4 (CodeWarrior Gold 11) or later. CWCVS
versions 2.4 and later require a Carbonized IDE, which means version 4.1
or later.
CWCVS also requires that you install a version of MacCVS on your machine.
MacCVS is a public domain implementation of a CVS client that is based on
the GNU implementation of CVS. We use the WinCVS.org
version 3.2b12 of MacCVS which can be downloaded
from SourceForge. This version
supports resource forks, an improved AppleEvent suite, project files, secure
shell and will run native under OS X.
The current CodeWarrior VCS architecture does not support creation of databases,
therefore you must either use existing CVS repositories or know how to create
new CVS repositories on the server. Moreover, CWCVS does not have a cvs
checkout facility, so you must use the MacCVS application to create
a workspace from an existing repository.
For those who wish to "roll their own" MacCVS from the public
domain source, CWCVS requires a local copy of an application with the creator
code specified in the CWCVS Options preferences panel that implements the
DoScript AppleEvent {'misc', 'dosc'} with the following parameters:
Do Command: Execute a CVS command
Do Command list -- Command line arguments, one per list item
[Mode AE/File] -- Mode (AE, File).
[Environment list] -- Environment variables.
[Filename string] -- Output file path.
[Pathway string] -- Starting pathway.
[NoLineBuffer boolean] -- if true, send each result line as separate AE.
Note that this is slightly different from the original event defined by
Mike Ladwig in that the arguments are no longer parsed from the list strings,
but copied directly. The keyword definitions are:
The environment variables are specified as pairs of adjacent entries in a list, namely <name> <value> <name> <value>... .
CWCVS also assumes that
Return to the Contents.
Simply copy the CWCVS folder into the CodeWarrior Plugins folder in your
CodeWarrior hierarchy. CodeWarrior should not be running when you do this.
If you do not have a copy of CWCVS, you can download
it from our web site. There is also a FAQ
if you have questions that are not covered by this manual, and some release notes describing the version change
history.
Return to the Contents.
Before using CWCVS with a project, you must first have a CVS repository
that is available to you via TCP. Documentation
on how to do this can be found in many places, but the best place to start
is probably the Cederqvist
manual.
Next, you need to have a project folder created by the cvs
checkout command. We strongly recommend that you do the initial
checkout with the version of MacCVS that you will use with the plugin. We
have found that different versions of MacCVS have slightly different file
formats which are mutually incompatible.
If you are using the recommended version of MacCVS, you can check in project
files by using the .mcp extension, so you may wish to rename your project
files. Also, if you have MacCVS configured to use Internet Config for extension
mapping, make sure that all the extensions in your project have the correct
mappings.
Return to the Contents.
To configure a project for use with CWCVS, do the following:
LOGNAME and $USER environment
variables);
pserver password) and check the
"Remember password" box;
Next, you should configure the VCS Environment Prefs panel. This tells CWCVS which repository you are talking to.To do configure it, do the following:
"CVSROOT=...";
CVSROOT environment variable;
Now, you should configure the VCSComment Prefs panel. This tells CWCVS how to color files using the Finder's labels. To do this, do the following:
If you are an experienced CVS user, you may wish to configure the default options for each command. To do this, do the following:
CVS maintains the "Local Root" directory specified above. It
is good practice to consider this directory as owned by CVS.
Return to the Contents.
This section is intended as a quick introduction to version control for the novice. We will take as a model an abstract programming project that may have one or more developers working on it and go through the entire process from start to finish. Note that this is not intended to be a comprehensive discussion of version control, nor is it our intention to imply that the CodeWarrior VCS model or GNU CVS are the last word in version control. For a list of all version control systems available for the Macintosh, as well as pointers to other online resources about version control and configuration management, please see our Macintosh VCS Page on the net.
Before we begin, a word about CodeWarrior. The CodeWarrior IDE has a plugin interface for Version Control Systems (VCSs) that is accessed through the VCS menu. This menu is an icon that looks like three stacked documents and appears when you have selected a VCS system to use from the Version Control Settings. The menu has two submenus, Project and Recursive, and you can bring up Advanced option dialogs for most commands by holding down the option key. Recursive commands apply to all the files under version control (or some obvious subset of them) and may have Advanced dialogs. You can force all regular commands to be enabled by holding down the command key.
Version control allows you to track different versions (or snapshots, if you will) of the files used to make a program (or anything for that matter, but we will stick to programming). While it is often used to keep track of the work of several developers, it can also be used quite beneficially by a single developer working alone. CWCVS itself has one developer, but uses version control to keep the older versions of its source files, resource files, project files and documentation organized and backed up. This manual itself is one of the files kept under version control.
The most important thing that version control does is to specify a database for storing all the versions of all the files in the project that is separate from the versions being worked on by a developer. This database, in addition to organizing all the revisions of all the files, also serves as a backup for the project. The first thing you do (as described in the previous configuration section) is specify a location for the database. If the database you specify does not exist, CWCVS will not allow you to connect. See the CVS documentation for information on how to set up a repository.
So that now you have a database, how do you add files to it? After you have added a new file to the project itself and are ready to preserve a version of it, you add a new file to the database with the Add command in the VCS menu. CVS will then schedule the file to be added to the database. You commit the new file to the database with the Checkin command. After committing the change, CWCVS locks the file so that you won't accidentally make changes to it.
Later on, you may need to make further changes to a file, say to add a feature or fix a bug. To unlock a file, you use the Checkout VCS command. The file will then be unlocked and you can start working on it. This is the part of the process that annoys many new users of version control. Try to remember that what you gain from tracking your changes and being deliberate about them generally outweighs the slight inconvenience of the checkout process.
Now, the bug is fixed and you want to save your changes in the database. You do this with the Checkin VCS command. You will be prompted for a comment describing what you did to the file. After checking in the file, the version in your workspace is locked again to prevent you from making accidental changes to it.
Occasionally, you will start to make changes and realize that you have been making them to the wrong file. If you check out a file in error, just use the Undo Checkout command to back out your changes and get a fresh copy from the database.
If you are working with a group, or if you have several machines where you work on your project, you may occasionally need to get individual files or even the entire source tree from the repository. You do this with the Get and Recursive Get commands. These will make sure that you have the latest versions of all your files. You can even get older versions of a file by holding down the option key and using the Advanced Get dialog.
One of the strengths of version control is that it enables you to track down changes by asking the database questions. CVS (on which CWCVS is based) allows you to ask it what files and revisions (snapshots) have certain properties. You make these queries with the History and Status commands. Another useful type of query is to compare the contents of a file that you have in your workspace with a version in the database, which is done with the Difference command. Finally, there is global information for the entire database (when it was created, etc.) and this is available from the Variables command.
Over the course of a project, files are created and added, but they are sometimes renamed, removed or even exported to another project. The VCS Rename command allows you to rename a file (although the IDE must be told to use the file with the new name). While CWCVS implements this operation for you, CVS has no rename operation, so a new file is created and the original history is part of the old file, which is deleted. The VCS Delete command doesn't actually delete the file, but it makes it so that it will not be used in the project any more (you can undelete it in MacCVS, but the CodeWarrior IDE does not have an interface for this operation).
Files are usually organized in a directory hierarchy, and CWCVS allows you to create a matching hierarchical database as you add directories. To do this, simply add a new file from the directory to the database. Be warned that the directory on the server may be created with odd access permissions that may have to be sorted out before other users can view these directories.
It's now time for the first beta to be released. When you do this, you may want to take a snapshot of the entire database. The Recursive Label VCS command allows you to create a symbolic name (or label) for this snapshot. This snapshot can be retrieved later with the Recursive Get command by holding down the option key and typing in the label name.
While all the operations described above are quite simple, requiring at most a comment string or a label, there are sometimes other options that you might want to specify, such as updating administrative information etc.. Holding down the option key while choosing a command will bring up a dialog box allowing you to specify such options. Some of the options are obvious; others (such as branching) are beyond the scope of this discussion. See the CVS documentation for more information.
The IDE allows you to perform VCS operations on the project file itself from the Project submenu. This is a good practice to get into as it make sure that all the information needed to rebuild your program is stored in the database, not just the source files.
CVS stands for "Concurrent Versions System" which means that several developers can be working on a file simultaneously. CVS merges changes together when you check a file in, and notifies you of any conflicts. This is usually not a problem, but it is quite different from most version control systems. This can cause problems with binary files, but CWCVS will warn you if you attempt to check out a binary file that someone else is editing, which allows you to coordiate your efforts.
Return to the Contents.
CWCVS supports the following commands in the IDE menu:
* CWCVS supports advanced (dialog) versions of these commands.
All cvs commands use the directory of the file being manipulated as the
cwd, or the local root directory for Recursive commands.
CWCVS attempts to make life pleasant for Kerberos
users. Before each command, $CVSROOT is checked to see if the ":kserver:"
string is present. If it is and if there is no valid ticket in the cache,
the login dialog is put up. Users who use Kerberos without the :kserver:
option must login separately.
Return to the Contents.
The Get command retrieves the current version of the file. The recursive
version updates all files in the project folder to their current versions.
All files are locked by default (including the project file).
Advanced dialogs are also available for both versions of the Get command. These dialogs allow you fairly complete access to all the various update options provided by CVS. These options are in two groups. The first group is used to make changes to the sticky tags associated with the file (or with the entire project). As part of the Get, you can change the default keyword expansion and update all the sticky tags associated with the file(s) begin gotten. The option you are mot likely to use here is "Reset sticky tags" to update how a file is treated (e.g. a file has been marked as binary and you need to copy that setting to your local workspace.)
The second group is used to specify which versions of the file and/or directories are retrieved. The first two checkboxes allow you to specify how any new or deleted directories in the repository are dealt with; the Revision popup allows to specify which date or revision you wish to update to; the last text fields allow you to merge branches of the source tree into the workspace. The most common options you would use here are the directory update options and specifying a particular revision to retrieve.
The cvs update command is quite complex and we recommend that you read the cvs documentation before attempting to do anything sophisticated.
The actual CVS commands are:
cvs -rq update [-k<keyword>] [-A] [-P] [-d] [(-r <revision> | -D <date>) [-f]] [-j<tag1> [-j<tag2>]] <file>
for the file version and:
cvs -rq update [-k<keyword>] [-A] [-P] [-d] [(-r <revision> | -D <date>) [-f]] [-j<tag1> [-j<tag2>]]
for the recursive version. None of the options are specified by default
Return to the Commands.
The Checkout command makes a file available for writing. This consists
of notifying cvs that you are about to edit the file and performing some
test to make sure you don't shoot yourself in the foot.
Mulitple edits of unmergable files (i.e. non-text files) are a constant source of argument in the world of CVS. In theory, such conflicts represent a management or process failure, but in practice, it is nice to have some sort of warning to back up the theory. Whenever you attempt to edit a file, the Checkout command checks for other editors and displays the list as a VCS Message.
Moreover, if the file is not a text file, CWCVS will ask you to confirm the edit. It will also check to make sure that there is not a more recent version of the file as the cvs edit command does not retrieve the most recent version (this is by design). Note that these features are intended to support the intended useage, not to enforce anything.
Note that "Checkout" is the IDE's term for setting write permission on a file and notifying the repository. This is completely unrelated to the cvs checkout command.
The actual CVS commands used are:
cvs -w edit <file>
for the edit:
cvs editors <file>
for the unmergable test.
cvs -nq update <file>
for the stale binary file test.
Return to the Commands.
The Checkin command commits the current version of a file to the
repository and locks it. The recursive version commits all locally modified
files. You will be prompted for a comment that describes what you are did
to the file(s). After checkin, the file(s) will be locked (including the
project file).
Advanced dialogs are also available for both forms of the command. the dialogs allow you to specify the branch or revision to commit to, and to turn off module processing for the checkin.
The actual CVS commands are:
cvs -r commit [-r <revision>] [-n] -m <comment> <file>
for the file version and:
cvs -r commit [-r <revision>] [-n] -R -m <comment>
for the recursive version.
Return to the Commands.
The Undo checkout command cancels the checkout of the file. It does
this by canceling the edit notification from the Checkout.
The actual CVS command used is:
cvs -r unedit <file>
Return to the Commands.
The History command displays a change history of the file obtained
from CVS. If you select multiple files, each one will appear in its own
window with a ".history" suffix. The recursive version returns
the history information for all files in the module.
The advanced dialog for the History command allows you to prune down the revisions and text displayed. Consult the CVS documentation for more information.
The actual CVS command used is:
cvs log [-h | -t | -R] [-N] [-b] [-d <dates>] [-s <status>] [-r<revisions>] [-w<editors>] <file>
for the regular version and:
cvs log [-h | -t | -R] [-N] [-b] [-d <dates>] [-s <status>] [-r<revisions>] [-w<editors>]
for the recursive version. No options are specified by default;
Return to the Commands.
The Status command displays the current state of the file, including
the revision numbers and sticky tags. If you select multiple files, each
one will appear in its own window with a ".status" suffix. The
recursive version of the command displays status information for the entire
project.
Advanced dialogs are also available for both versions of this command. They allow you to list all tags associated with a file.
The actual CVS command used is:
cvs status [-v] <filename>
for the regular version and:
cvs status [-v]
for the recursive version.
Return to the Commands.
The Properties command displays the watchers or editors of the file.
If you select multiple files, each one will appear in its own window with
a ".watchers" or ".editors" suffix. The recursive version
of the command displays watchers or editors for the entire project.
The advanced version of this command is used to toggle between displaying the watchers and editors. Hold down the option key to display the editors.
The actual CVS commands used are:
cvs watchers <filename> cvs editors <filename>
for the regular versions and:
cvs watchers cvs editors
for the recursive versions.
Return to the Commands.
The Difference command allows you to compare a file to the repository
version. There are two flavors of the Difference command, the original CVS Difference which uses the cvs
diff command, and a Helper Difference,
which uses the IDE and helper applications to display differences. The flavor
in use is controlled by a checkbox in the CWCVS Options panel, and the default
is to use Helper Difference.
The regular version compares the local file to the current revision in the repository and the advanced version of the command allows you to specify which revision of the file to compare with the local revision, with a choice of revision, date or the main branch. The recursive version will show the differences for every file that is checked out or unlocked, comparing each to the current revision in the repository or to a version that you specify.
Difference is accomplished by use of helper applications. The default helper for text files is the CodeWarrior IDE and the default for resource (RSRC, rsrc) files is Mathemaesthetics' Resourcerer. For older versions of the IDE, the difference is redirected to a helper application that translates the event for Bare Bones Software's BBEdit.
The actual CVS command used is:
cvs checkout [-r <rev> | -D <date>] <repository file path>
By default, the -r <rev> option is used, where <rev> is the base revision for the file. The file is checked out to the temp directory on the same volume as the original file and then moved to the top of the temp folder. The cvs checkout folders are then deleted as they are not needed.
The helper applications mapping is described by the CTM# resource. The Compare Apple Event used is as follows:
Class: Comp Event: Comp Parameters: Newer file: kNew (typeFSS) Older file: kOld (typeFSS) Show difference: kShD (typeBoolean)
You may need to write a mapping applet to translate the event to your helper application.
The regular version compares the workspace version to the revision it was derived from. If you select multiple files, each one will appear in its own window with a ".diff" suffix. The advanced version of the command allows you to specify which revisions of the file to compare, how to expand RCS keywords and various diff options. The recursive version will show the differences for every text file that has been modified. The advanced recursive version will show all differences between any sets of files in just about any manner you could want.
The actual CVS commands used are:
cvs diff [-k<keyword option>] [-r <tag1> | -D <date1> [-r <tag2> | -D <date2>]] [-c] <file>
for the regular version and:
cvs diff [-k<keyword option>] [-r <tag1> | -D <date1> [-r <tag2> | -D <date2>]] [-c]
for the recursive version. Only the -c option is specified by default.
Return to the Commands.
The Label command allows you to label the state of a module so that
you can refer to it later. The command will prompt you for a label to use
for the module. You can later use the Recursive Get
command to retrieve this set of source and work with it.
CVS actually has two label commands: one labels the revisions currently in your workspace; the other labels the revisions currently in the repository. The regular Label command works with the revisions in the workspace and the advanced Label command (hold down the option key) works with the revisions in the repository.
The actual CVS commands used are:
cvs tag [-F] [-b] [-c] [-d] <tag>
for the regular command and:
cvs rtag [-F] [-a] [-c] [-d] [-R <rev> | -D <date>] [-f] <tag> <local root name>
for the advanced version. Only the -F option is specified by default.
Return to the Commands.
The Comment command allows you to change the checkin comment for
a version of a file. You will be asked for a new comment.
The regular version changes the comment for the file version that you re currently working on. The advanced version of the command allows you to specify which revision of the file to change the comment for.
The actual CVS command used is:
cvs admin -m<rev>:<msg> <file>
and for the Regular command, <rev> is taken from the :CVS:Entries file.
Return to the Commands.
The Rename command changes a file's name in the repository. It does
this in the recommended manner, namely by renaming the file locally, deleting
the old file and adding the new file. After the rename, the file is labeled
as checked out and can now be checked in. The IDE does not know that the
file has been renamed, so you must add the new version manually before doing
the checkin.
The actual CVS/POSIX commands used are:
mv <old name> <new name> cvs remove <old name> cvs add <new name>
Return to the Commands.
The Add command adds a new file to the local repository. It does
not commit it. After the add command, the file is labeled as checked out
and can now be checked in. By default, non-text files are checked in as
binary files. By holding down the option key, you can specify a file description
and a keyword option for the file.
Before adding a file, the Add command checks to make sure that the directories below the local root that contain the file are in the repository. If not, it will prompt you (from the top down) to add the directory.
The actual CVS command used is:
cvs add [-k<keyword> [-m <description>] <file name>
The -kb option is specified by default for non-text files. When adding a directory, the CVS command used is:
cvs add <directory name>
with the cwd set to the directory's parent. The test to determine whether the directory exists is simply to check for the CVS directory.
Return to the Commands.
The Delete command schedules a file to be deleted from the repository.
It does not commit the deletion.
Unlike CVS, the IDE expects the file to only be deleted from the repository
but not from the local drive, which means that once the file has been deleted,
the only way to commit the deletion is to use the Recursive
Checkin command.
After committing, the file is still in the repository attic, but the IDE
has no interface for recovering it.
The actual CVS command used is:
cvs remove <file>
Return to the Commands.
The Connect command makes sure that MacCVS is available and fails
if it is not. In addition, if you are using a pserver connection
method and you are not logged in using the username/password specified,
CWCVS will attempt to log you in. If your password is not valid, the connect
will fail.
If the connection method is pserver then a cvs login is faked by adding the password to the .cvspass file and then attempting to issue a
cvs -nq update -l
command. If this fails, the .cvspass file is restored and the connection fails.
Return to the Commands.
The Disconnect command is currently a nop.
Return to the Commands.
The About command displays a dialog box with version information.
Return to the Commands.
The Variables command displays information about the project, including
the status of all the files.
The actual CVS command used is:
cvs status
Return to the Commands.
This software should do what is described in this document. If it doesn't,
you can simply stop using it. If you pay for it, and within a year find
that it doesn't do what is described here, then you can notify us and we
will refund your money and cancel your license.
Electric Fish, Inc. hereby disclaims all warranties relating to this software,
whether express or implied, including without limitation any implied warranties
of merchantability or fitness for a particular purpose. Electric Fish, Inc.
will not be liable for any special, incidental, consequential, indirect
or similar damages due to loss of data or any other reason, even if Electric
Fish, Inc. or its agent has been advised of the possibility of such damages.
In no event shall Electric Fish, Inc. be liable for any damages, regardless
of the form of the claim. The person using the software bears all risk as
to the quality and performance of the software.
This code contains calls to the MIT KClient library for authentication only.
Such use is not prohibited for export by US law. Because of this, we are
required by MIT to include the following notice from them regarding the
KClient code:
Copyright (C) 1989 by the Massachusetts Institute of Technology
Export of this software from the United States of America is assumed
to require a specific license from the United States Government.
It is the responsibility of any person or organization contemplating
export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
notice appear in all copies and that both that copyright notice and
this permission notice appear in supporting documentation, and that
the name of M.I.T. not be used in advertising or publicity pertaining
to distribution of the software without specific, written prior
permission. M.I.T. makes no representations about the suitability of
this software for any purpose. It is provided "as is" without express
or implied warranty.
Government End Users: If you are acquiring the Software and fonts on behalf of any unit or agency of the United States Government, the following provisions apply. The Government agrees:
Return to the Contents.