Tekkotsu CVS Usage

Background:

CVS stands for Concurrent Versions System, a commonly used method of maintaining modification history for files, allowing many users to collaborate in an organized fashion.

You can browse our CVS repository through the Tekkotsu CVS web interface.

Setup:

For additional help regarding the options available for any command, type:
    cvs --help command
 The general form of CVS commands is:
    cvs [global options] command [command-specific options]
Thus, some flags must be given before the command and are always available, whereas others are command specific and must follow the command they apply to.

You can create a .cvsrc file in your home directory which will be checked for default parameters, allowing easier command line use.

Initial Checkout:

  1. Log into the server:
    cvs -d :pserver:anonymous@cvs.tekkotsu.org:/cvs login
  2. Change to the directory which you would like to contain the Tekkotsu framework
    cd /usr/local; # or other location of your choosing
  3. Check out the source:
    cvs -d :pserver:anonymous@cvs.tekkotsu.org:/cvs checkout -P Tekkotsu
  4. Configure your installation.

Updating:

Updating the Tekkotsu framework itself is fairly straightforward.  However, you will also need to make sure that any projects you have started are updated as well in order to take advantage of new tools or build features.

  1. It may be wise to back up your framework and project(s) before updating, just in case unexpected problems arise.
  2. From the main Tekkotsu directory:
    cd tekkotsu_root; # tekkotsu_root is usually /usr/local/Tekkotsu

# ONE of the following options:

# ** Update to cutting edge development
cvs -q update -d -P -A

# ** OR update to latest "stable" development
cvs -q update -d -P -r STABLE

# ** OR update to latest release
cvs -q update -d -P -r tekkotsu-
  4. The output from CVS will report the status of each file which has been touched.  The status codes are:
    In the output of CVS, look for files marked with a 'C' - these signal a conflict was found between changes made in the repository, and changes made to your local files.  CVS is often able to resolve these conflicts itself, but it is not always able to do so.
    If a conflict occurs:
    1. Open the conflicted file in your editor of choice
    2. Each conflict in the file will be marked in the form:
      <<<<<<<
      your code here
      =======
      new code here
      >>>>>>>
    3. Decide which version of the file you wish to keep, or how to merge the differences

  5. Repeat previous steps for each of your projects as well. (projects need to stay in sync with framework version)

Advanced Updating:

For heavy development you may wish to put your project directory in your own versioning system to allow collaboration, archiving, historical analysis, etc. of your own project.  There are other systems available besides CVS, which may allow you to update from the Tekkotsu repository through CVS without clashing with your own repository's settings.

However, if you wish to use CVS for your own versioning as well, there would be a conflict between the CVS status information for your repository, and the CVS information for the Tekkotsu repository.  Don't give up yet though, updating your project from Tekkotsu source is still possible, but a little more complicated.

Method A: CVS "Dual-Citizenship"

One method is to keep two versions of your CVS directories, and swap them back and forth when it's time to update from the other source. Something like: 
# swap from local repository to Tekkotsu repository:
find . -name "CVS" -exec mv \{\} CVS-local \;
find . -name "CVS-Tekkotsu" -exec mv \{\} CVS \;

# get update from the main repository:
cvs update

# swap back to your local repository:
find . -name "CVS" -exec mv \{\} CVS-Tekkotsu \;
find . -name "CVS-local" -exec mv \{\} CVS \;

Method B: Symlink unmodified portions

You can also checkout a normal project template, and then use symlinks from your custom project into the template project for the portions which you want to retain the template, such as the Makefiles (i.e. Makefile, aperios/Makefile.aperios, local/Makefile.local)

Method C: Generate Patchfiles

Another method is retain a pristine copy of the original project template, and then when you want to update, checkout a fresh copy of the project directory.  Generate a patch from the old project to the new project (we generate and distribute this patch file for each Tekkotsu stable release). 
# NOTE: do this stage BEFORE you update the framework!
# (that's a later step)

# NOTE: if your project template has been customized, you'll need to
#       determine the date and time you last updated/checked out, and
#       check out a fresh copy to diff the new version against
#       tekkotsu_root/tools/cvsCheckoutDate can help find the timestamp

cd tekkotsu_root/project; # tekkotsu_root is usually /usr/local/Tekkotsu
make cleanProj; # prevent spurrious diff'ing of generated files

#get latest version of project directory (into '/tmp/curproj')
# 'rm -rf /tmp/curproj' if it already exists
cvs -d :pserver:anonymous@cvs.tekkotsu.org:/cvs checkout -Pd /tmp/curproj Tekkotsu/project

# generate patch to sync local to repository
diff -u -r -N -a --binary --exclude=CVS . /tmp/curproj > /tmp/current.patch

For each of your customized projects, apply the patch and resolve any conflicts that occur:
# apply patch to sync local to repository
cd /path/to/your/project
patch -p0 < /tmp/current.patch; #bring project up to date

Finally, update the Tekkotsu framework itself, as was shown for the "easy" updates:
# could be done anytime after first stage (patch generation)
# is complete but better to wait until patch is applied
# successfully, just in case
cd tekkotsu_root
cvs update -d -P -A; #update framework to latest version

Generating Patches for Submission:

Please review the FAQ entry on the subject first.

If you have made changes to the framework which you would like to submit for inclusion, the following commands will usually do the job:
#SIMPLE METHOD - only catches modified, pre-existing files
# (attach new files to submission manually)
cd tekkotsu_root
cvs diff -u -b > your_submission.patch
Please review the patch to make sure it includes everything you expect it to.  If you have created any new files, you'll need to attach them as well.

Alternatively, you can try this method for generating a patch file, which is more guaranteed to catch all modifications in a single patchfile, and will work if your own copy of the framework wasn't checked out of CVS:
#ALTERNATIVE METHOD - more general, catches all modifications
# in single patch

#get latest version of project directory (into '/tmp/curproj')
# 'rm -rf /tmp/curproj' if it already exists
cvs -d :pserver:anonymous@cvs.tekkotsu.org:/cvs checkout -Pd /tmp/curproj Tekkotsu/project
cd tekkotsu_root;
diff -urbNa --binary --exclude=CVS --exclude=build /tmp/curproj . > your_submission.patch