CWProjector
is a version control plugin for Metrowerks
CodeWarrior which allows you to use MPW's Projector for source control without
leaving the CodeWarrior IDE.
CWProjector
provides an easy to use source-code control system, at minimal cost, using
established technology from Apple. It
is well suited for individuals and small organizations which want the benefits
of source-control with a minimum of hassle and expense.
If you are new to version control, you may wish to start by reading the
Version Control Basics section. Otherwise, keep
reading.
Return to the Contents.
CWProjector provides the standard functions of most source-code control systems:
and several additional features:
Return to the Contents.
CWProjector requires a version of the CodeWarrior IDE that supports the
VCS plugin architecture. This means version 1.7.4 (CodeWarrior Gold 11)
or later. You also need the PluginLib4 library from Metrowerks to support
the Difference command with IDE versions 3.0 and 3.1. Note also that because
the 68K VCS libraries are broken that 68K support is only available with
IDE 3.0 and later via CFM68K.
CWProjector also requires that you install a version of MPW SourceServer
on your machine. SourceServer, a standalone application that provides access
to most of the Projector commands found in the MPW shell, is included with
CodeWarrior, or you can download
it from Apple's ftp site. For system 8.5 we recommend at least SourceServer
version 3.5.d4 from Apple.
Note that all you need is to have the SourceServer application on a local
drive: the CodeWarrior documentation is for users who want to use SourceServer
from the IDE's ToolServer menu - a far less elegant solution than CWProjector.
Be aware that SourceServer will not work when run from a remote volume -
you must have it locally on your drive.
The default application for doing resource-based Differences is version 2.2 of Mathemaesthetics' Resourcerer
product. We highly recommend this resource editor.
Return to the Contents.
Simply copy the CWProjector folder into the CodeWarrior Plugins folder
in your CodeWarrior hierarchy. If you are using versions 3.0 or 3.1 of the
IDE, you will also need to place the PluginLib4 library next to the application.
if you are using version 1.7.4 of the IDE, you will need to change the preferences
panel file types to 'Panl' using some sort of file editing tool such as
Resourcerer.
If you do not have a copy of CWProjector, 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.
If you have problems with CWProjector that are not covered by the FAQ or the
release notes, please use the enclosed form
to submit a bug report.
Return to the Contents.
Before we begin, a quick word about terminology is in order. Projector
and CodeWarrior both use the term "project". In this documentation,
we use the CodeWarrior terminology, hence project refers to a CodeWarrior
project and database refers to a Projector project.
Prior to using CWProjector with a project, you must first decide where you
wish to keep the Projector database. If your project already has one, you
only need to make sure that the volume is mounted. If you don't have a Projector
database, CWProjector can create on for you, but you must create an empty
folder in the desired location with the desired name (so that the IDE can
be pointed at it). The first time you connect, CWProjector will convert
this folder to a Projector database. CWProjector works with subdatabases,
but it requires that the main database be a top-level database.
The CodeWarrior VCS model assumes that all the files subject to version
control are in a single directory hierarchy. CWProjector interprets this
as a directory hierarchy that matches the Projector database hierarchy,
so make sure that your files are in this form. This also means that while
CWProjector can easily handle a database with multiple subdatabases, it
does not let you switch to a different top-level database or use multiple
top-level databases.
If you wish to use version control on your project file itself, you need
to have it in this local hierarchy. You can use an alias to the project
file for easy launching.
Return to the Contents.
To configure a project for use with CWProjector, do the following:
At this point, you should configure the VCSComment Prefs panel. To do this, do the following:
If you are an experienced Projector user you may wish to configure the default options for each command. To do this, do the following:
CWProjector maintains the "Local Root" directory specified
above. It is good practice to consider this directory owned by CWProjector.
For example, CWProjector will delete obsoleted files from this directory
when performing a Recursive Get operation.
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 MPW Projector 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.
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. CWProjector 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, CWProjector will create one for you when you start up version control for a project.
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. A copy of the file is then added to the database and the version you have in your workspace is locked to prevent you from making accidental changes to it. When you add the file, you must specify a change comment describing what you did. This happens every time you submit a file to the database, making it easier to go back and find when you made certain changes.
Later on, you may need to make further changes to a file, say to add a feature or fix a bug. You need to tell the database that you want to make changes to the file and keep other developers from making changes to that file while you are working on it. You do this with the Checkout VCS command. You will be asked for a comment describing what you intend to do with the file (which can be very useful if you forget before you check it in) and 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 usually 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 again be prompted for a comment describing what you did to the file. Under CWProjector, the checkout comment is on the clipboard and the last checkin comment you provided is the default in the dialog, which gives you two possibilities to start from. 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.
If you are working with a group, or if you have several machine 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.
CWProjector provides a useful feature called "Header Comments" as part of the checkout/checkin process. If you enable this feature, CWProjector will place a running history of the checkin comments with dates and initials at the top of each source file. This can be very handy for tracking down changes quickly. You can also get this information from the database, but it is a separate command and requires the database. CWProjector can also change the Finder Label of files to match their checkout state, which can be a useful way of tracking what files you are modifying.
One of the strengths of version control is that it enables you to track down changes by asking the database questions. Projector (on which CWProjector is based) allows you to ask it what files and revisions (snapshots) have certain properties. You make these queries with the Properties, 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). 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 MPW, but the CodeWarrior IDE does not have an interface for this operation). The VCS Purge command is used to remove the version control information from a file so that it can be added to another database.
Files are usually organized in a directory hierarchy, and CWProjector 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.
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 choosing the label from the popup. Files can also be labeled one at a time with the Label command to allow you to refer to a group of related changes as a unit.
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 keeping a file checked out when checking it in and so on. 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 MPW Command Reference 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.
Return to the Contents.
CWProjector supports the following commands in the IDE VCS menu:
* CWProjector supports advanced (dialog) versions of these commands.
Note that the command names are determined by the IDE, not by CWProjector.
If you are a devoted Projector user, please refer to the command descriptions
to determine what each one does.
Note also that the default behavior for each command can be customized
in the "CWProjector Options" preferences panel. The options in
this panel correspond to the check boxes in the advanced dialogs and are
the options used in the regular versions of the commands.
If you are unfamiliar with the Projector commands and would like to learn
more, please refer to the Apple manuals "Building
and Managing Programs in MPW, 2nd edition", "MPW
Command Reference" and "SourceServer
Reference".
Return to the Contents.
The Get command retrieves file versions from the Projector database.
It has a recursive version that allows you to update the entire project
and advanced versions that allow you to customize the checkout. The Get
command will also check to see if the file is ModifyReadOnly and ask you
if you wish to discard the changes. If the file does not exist, CWProjector
will still attempt to get the file.
The regular Get command simply gets the latest version of a file from the
database. The regular Recursive Get command refreshes the entire project
folder with the latest versions of all files and deletes any obsolete files.
These are the most common operations that you would want to perform.
The advanced Get commands (available by holding down the option key) allow
simple access to the Projector CheckOut command in all its baroque glory.
We have attempted to provide options that we believe that most users will
want access to. The advanced version of the regular Get command allows you
to specify several options and to choose which version of the file you wish
to CheckOut. The advanced version of the Recursive Get command again allows
you to select among various options, but also to choose between getting
the latest versions of all the files or getting a particular NameRevision
(which is called a Label by CodeWarrior). You can define NameRevisions from
CWProjector using the Label command.
The actual Projector commands are:
CheckOut <options> -d <dir> -project <project> <file>
for the single file version and:
CheckOutDir -r -project <project> <dir> CheckOut <options> -r -project <project>
for the recursive version. The default options for the regular version of these commands are described below.
The advanced options available for the Get command are:
[-history] [-noTouch] [-verify]
-noTouch is specified by default. In addition, specific
versions of the file may be chosen from a list.
The advanced options available for the Recursive Get command are:
[-deleteObsolete] [-history] [-noTouch] [-verify] [-newer | <label>]
-deleteObsolete, -noTouch and -newer are specified by
default.
The commands:
OrphanFiles <file> CheckOut -y -d <dir> -project <project> <file>
are used for MRO files.
Return to the Commands.
The Checkout command retrieves the latest version of the file from
the Projector database and makes it available for writing. You will be prompted
for a comment that describes what you are doing. If you are using header
comments, this comment will be added to the header. The Checkout command
will also check to see if the file is ModifyReadOnly and ask you if you
wish to discard the changes. The advanced Checkout command allows you to
specify various Projector Checkout options such as the task name and file
verification.
There is also a Recursive version of the Checkout command. All this does is a tree walk allowing you to check out all the files you have locally. The Advanced version will put up the checkout dialog for each file. This Recursive variation should not be used casually as this tends to defeat the purpose of Version Control (not to mention being highly obnoxious in a shared environment!) It is mostly useful for when you have to change every file at once. If there is any file that you do not need to modify in the edit, you should strongly consider checking the files out individually.
Note that this is slightly different from the Projector CheckOut command which also allows you to retrieve a file read-only. In CWProjector this functionality is provided by the Get command.
The actual Projector command used is:
CheckOut -m <options> -cs <comment> -d <dir> -project <project> -u <user> <file>
The advanced options dialog (available by holding down the option key) brings up a dialog that allows you to specify the following options:
[-b] [-history] [-noTouch] [-verify] [-t <task>]
as well as the version you wish to check out. -noTouch
and the latest version are specified by default.
The commands:
OrphanFiles <file> CheckOut -y -d <dir> -project <project> <file>
are used for MRO files.
Return to the Commands.
The Checkin command returns the edited version of the file to the
Projector database and locks it. You will be prompted for a comment that
describes what you are did to the file. If you are using header comments,
this comment will be added to the header. If you specified a task name during
Checkout or later via the Advanced Comment command, that task will be used for the checkin.
The Advanced Checkin command allows you to specify several checkin options, including changing the task name and a new version name. If you specify a new version name it must be numerically greater than the current version.
The recursive versions of the checkin command walk the Local Root directory
searching for files that are checked out or MRO. It then prompts you to
check in each one. It is just as if you selected all the checked out files
in the project window and chose Checkin.
Because the IDE does not allow a default comment to be passed when bringing
up the comment dialog, the checkout comment is copied to the scrap before
bringing up the dialog. You can then paste it into the text field if you
like. The IDE also does not enable the Checkin command for MRO files, so
to check in an MRO file you must hold down the command key while choosing
"CheckIn" from the VCS menu.
The actual Projector command used is:
CheckIn <options> -cs <comment> -project <project> -u <user> <file> [-t <task>]
The advanced options dialog (available by holding down the option key) brings up a dialog that allows you to specify the following options:
[-b] [-m | -delete] [-touch] [-verify] [-t <task>]
None of these options are specified by default, except the task as described
above.
Return to the Commands.
The Undo Checkout command cancels the checkout of the file. It can
also be used with an MRO file by holding down the command key.
The recursive version prompts you to cancel the checkout of all checked out or MRO files. It is just as if you selected all the checked out or MRO files in the project window and chose Undo Checkout.
The actual Projector command used is:
CheckOut -cancel -y -d <dir> -project <project> <file>,<rev>
The commands:
OrphanFiles <file> CheckOut -y -d <dir> -project <project> <file>
are used for MRO files.
Return to the Commands.
The History command displays a change history of the file obtained
from the Projector database. It displays information for each revision in
the database, including the author, checkin date, task and comment fields.
If you select multiple files, the history for each file will appear in a
separate window with a ".history" suffix. The recursive version
returns the comment information for all file revisions in the project that
are checked out for modification (this is because returning all information
for all files will probably overflow the SourceServer return buffer). The
History command also supports advanced versions of both the regular and
recursive commands.
The Advanced version of the command allows you to filter the reporting of the versions of the selected files by giving a matching pattern for the author, comment, modification dates, task and name, or by specifying the latest trunk version. Leaving a field blank means that no filtering is done with it. You may also specify whether the history of each file appears in its own window or in a single window; that file information only be displayed; and that a short listing be given. The latter causes the comments to be stripped out, giving you only a list of version or the history.
The Advanced Recursive version of the command allows you to specify the versions of the selected files as in the Advanced version, as well as specifying which files are reported on. Files can be specified by author, comment and date, and by various version tests. The popup allows you to ask for all files or files that there are newer versions of in the database than the ones you have, including or excluding any new files you don't have copies of yet. You can also ask for only the files that someone has open for modification, which can be very useful for making sure you have everything checked in (finding "lurkers"). Finally, you can specify short listings as for the regular version of the command.
For the author, comments and task, you can specify a pattern that the field must contain, either a literal string, or a regular expression enclosed in forward slashes (/).
The date can be specified as follows:
A date used in a date expression can be specified as
mm/dd/yy [ hh:mm [:ss ] AM|PM ]
where mm, dd, and yy represent the month, day, and year; hh, mm, and ss represent the hour, minute, and second; and AM and PM indicate an A.M. or P.M. time.
For the name, you can specify either a label name or a version number. The name can be specified as follows:
The actual Projector command used is:
ProjectInfo <filename> -project <project> -comments <file name>
for the regular version and:
ProjectInfo <filename> -project <project> -comments -r
for the recursive version. The Advanced version adds the options:
[-a <author>] [-c <comment>] [-d <date>] [-n <name>] [-t <task>] [-latest] [-f] [-s]
and the Advanced Recursive version adds the options:
[-newer | -update] [-af <author>] [-cf <comment>] [-df <date>] [-m] [-s]
Return to the Commands.
The Status command displays the current state of the file, as recorded
in the 'ckid' resource and updates the displayed status in both the IDE
and the Finder. If you select multiple files, the status for each file will
appear in a separate window with a ".status" suffix.
The recursive version checks the status of every file in the Local Root directory and places the results in a single window with a ".status" suffix. Only files with 'ckid' resources are reported, but the IDE and Finder status of every file is updated. This is very useful for synchronizing the status with the disk and also for forcing the IDE to update as Synchronize Status does not always work well with 'ckid' files.
The Advanced version of the command allows you to specify that a single window is used.
The Advanced Recursive version doesn't actually put up a dialog, but reports only those files that are checked out or MRO.
No Projector commands are used.
Return to the Commands.
The Properties command displays the current state of the file, including
the author, creation and modification dates and whether the file can be
checked out. If you select multiple files, the status for each file will
appear in a separate window with a ".properties" suffix.
The Properties command is actually almost identical to the History command, except that Properties doesn't display the checkin comments for non-short listings.
The actual Projector commands used are the same as for the History command, except that the
-comment
option is not specified.
Return to the Commands.
The Difference command displays the differences between the version
of a text or resource file in your workspace and a version in the database.
The regular version compares the main trunk revision and the advanced version
of the command allows you to specify which version of the file to compare
with the disk version. The recursive version will show the differences for
every file that is checked out or MRO as compared to the main trunk revision.
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 old versions of the IDE, the difference is redirected to a helper application that translates the event for Bare Bones Software's BBEdit.
The actual Projector commands used are:
CheckOut -d <temporary dir> -project <file project> <file name>[,<version>]
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.
Return to the Commands.
The Comment command allows you to change the Checkout comment for
a file. Although the IDE enables it for all files, it only functions for
files that are checked out or modifiable. Other files will give an error.
The comment is changed in the 'ckid' resource and in the header comment.
The advanced version of the command changes the Checkout Task Name for a
file in the 'ckid' instead of the comment.
The recursive versions of the command specify the comment/task name for all checked out or MRO files in the Local Root. It is just as if you selected all the checked out files in the project window and chose Comment.
No Projector commands are used.
Return to the Commands.
The Label command allows you to label a group of files so that you
can refer to them later as a group. The command will prompt you for a label
to use for all selected files. You may later use a label you have defined
in the advanced recursive Get command. Note: This
is not the same as Finder coloring (which is also called Labeling). In order
to recursively label all files, you must hold down the option key: the regular
recursive command lists all the existing labels.
In addition to the name of the Label, you may also specify whether you wish to replace an existing label with the same name, have the label always refer to the latest version of a file or specify that the local revision that you have in your workspace be the revision used. The last two options are mutually exclusive, and if neither is specified, the labeled revision will the the latest version checked in.
The actual Projector commands used are:
NameRevisions <name> [-replace] [-dynamic] -u <user> -project <project> <revision>...
for single files and for the recursive version with local revisions specified; and:
NameRevisions <name> [-replace] [-dynamic] -u <user> -project <project> -r
for the recursive version. When specified, the replace option is only
used for the first Projector command used in the VCS command.
Return to the Commands.
The Rename command allows you to rename a file in the Projector database.
CWProjector will prompt you for a new name for each file, renames the file
in the database, orphans the old file and checks out the new file for you.
Warning! The IDE does not update itself to reflect the
renaming, so you must do it manually.
The actual Projector commands used are:
RenameProjectorFile -project <project> -u <user> <filename> <new name> OrphanFile <file> CheckOut -d <dir> -project <project> <new file>
Return to the Commands.
The Add command checks a new file into the Projector database. If
you are using Header Comments, you will be asked to give a brief description
of the contents of the file for the header. If the file already has a header
comment, you will be asked whether you wish to reuse it. if you answer yes,
the entire header (including the old change history) will be kept and a
new history started at the top of the change history section.
If the file is in a folder for which there is no corresponding subdatabase,
CWProjector will attempt to create subdatabases. For each subdatabase, you
will be asked if you wish to create it and for a creation comment. If you
cancel at any point, the Add will fail and that particular subdatabase will
not be created. Previously created databases will not be backed out.
The actual Projector command used is:
CheckIn [<options>] -new -cs <comment> -project <project> -u <user> <file>
The advanced options dialog (available by holding down the option key) brings up a dialog that allows you to specify the following options:
[-m | -delete] [-touch] [-verify] [-t <task>]
The task is set to the last task you entered (if any). None of the options
are specified by default.
For subproject creation, the command used is:
NewProject -u <user> -cs <comment> <database path>
Return to the Commands.
The Delete command removes a file from the Projector database and
orphans the file.
After deletion, the file is still in the database as an obsoleted file,
but the IDE has no interface for recovering it. You must use the MPW command
UnObsoleteProjectorFile.
The actual Projector command used is:
ObsoleteProjectorFile -project <project> -u <user> <file> OrphanFiles <file>
The MPW shell syntax for the Projector UnObsoleteProjectorFile command is:
UnObsoleteProjectorFile -project <project> -u <user> <file name>
Return to the Commands.
The Purge command orphans the file but does not remove it from the
database. The Recursive version orphans every file in the Local Root directory.
You will be prompted for each file and can specify "Yes" to orphan
the file, "No" to skip a file and "Cancel" to abort
the rest of the operation.
After purging, the file is still in the database, but the local copy has
no 'ckid' resource and the IDE will display it as not being in the database.
To recover the file, you must use the Get command.
Purge is most useful for importing files from another database. You copy the file into the local source directory and add it to the project. After Purging the file, you can now add it to the current database.
The Recursive Purge command is most useful for exporting a source tree. After getting copies of all the files to export, you can issue the Recursive Purge to orphan all the files. You can then connect to a new database and start adding the files again.
The actual Projector command used is:
OrphanFiles <file>
Return to the Commands.
The Connect command launches SourceServer and mounts the top level
Projector database.
If the top level database does not exist, CWProjector will attempt to create
the it. The location was originally specified in the VCS Setup panel as
an empty folder with the correct name. You will be asked whether you wish
to replace this empty folder with a database and for a creation comment.
If you cancel at any point, the Connect will fail and the top level database
will not be created.
The actual Projector command used is:
MountProject <database path>
For top level database creation, the command used is:
NewProject -u <user> -cs <comment> <database path>
Return to the Commands.
The Disconnect command is required by the IDE, but does nothing.
Return to the Commands.
The About command displays a dialog box with version information.
Return to the Commands.
The Variables command displays information about all the member projects.
The information appears in a window with a ".variables" suffix.
The actual Projector command used is:
ProjectInfo -project <projectName> -only -r
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.
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.