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
    • This step is not strictly necessary depending on your version of the CVS client
    • -d tells CVS to connect to the server specified in the argument that follows it
    • Use your email address as your password
  2. Change to the directory which you would like to contain the Tekkotsu framework
    cd /usr/local; # or other location of your choosing
    • If you choose a location other than /usr/local, you will need to change the TEKKOTSU_ROOT value in Environment.conf after the initial checkout is complete.  See the Tekkotsu configuration instructions for assistance.
  3. Check out the source:
    cvs -d :pserver:anonymous@cvs.tekkotsu.org:/cvs checkout -P Tekkotsu
    • This will get the latest version of the source, and will be stored in a directory named Tekkotsu.
    • -P will remove ("prune") empty directories which once held files, but are no longer used.
  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_0_1
    
    • -q will tell CVS to be quiet, displaying minimal status information -- makes the next step easier
    • -d will check if any new directories have been added
    • -P will remove ("prune") empty directories which once held files, but are no longer used.
    • You have two options for the last flag:
      • -A tells CVS to clear the previously specified tag and update to the absolute latest version.
      • -r tells CVS to use the tag given by the parameter which follows:
        • HEAD is a special tag which always refers to the most recent version
        • STABLE is the latest "stable" point, which will lag behind the HEAD by a little bit when we introduce new features until we've had a chance to test them.
        • Releases are tagged in the format: tekkotsu-MAJOR_MINOR_BUG
          For example, the tag for version 3.0 was tekkotsu-3_0, 2.4.1 was tekkotsu-2_4_1
  3. The output from CVS will report the status of each file which has been touched.  The status codes are:
    • U - file was updated with respect to the respository.
    • P - file was patched with respect to the repository. Same as update.
    • M - file has been modified in your working directory.
    • C - conflict detected while trying to merge your changes to file with changes from the repository.
    • ? - file is in your working directory, but does not correspond to anything in the source repository.
    • A - file has been added to your private working directory. Needs to be commited.
    • R - file has been removed from your working directory. Needs to be commited.
    • I - file is being ignored e.g. an object file.
    • N - file is a new file which has been checked into the repository.
    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

  4. 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

developer resources

Last modified: 2010-07-26