Welcome.

     Tuesday, September 14, 2004     Refactoring your project layout with CVS modules

Many of us have projects in CVS that are organized based upon decisions that were made (and forgotten) long ago. Since one of the limitations of CVS is that is not easy to move directories, many groups will simply dump their repository, and reorganize it when refactoring their project layout (for example to better support J2EE project hot deploy).

This has the disadvantages of losing existing repository history, forcing all build/deploy scripts to be rewritten at the same time, as well as forcing all developers to adopt the new module at the same time. But fear not, you can frequently change the layout of your development tree by using CVS modules and retain your file history, keep all existing build and deploy scripts, and gradually transition users to the new layout.

CVS modules are a way of providing logical names for directories within your repository. Modules come in three varieties: alias modules, regular modules, and ampersand modules. Modules are defined in the modules fine in CVSROOT. To get access to this file, checkout the module CVSROOT, edit the modules file, and commit it.

Alias modules-- alias modules are the simplest type of module, and are not very helpful to us. I can define an alias module by specifying the following in modules:

     amodule -a dir1 

You can then use the name amodule or dir1 interchangeably and both act the same.

Regular modules -- regular modules are much more helpful in this task since regular modules allow us to define modules that point to an arbitrary point in our existing repository. When these are checked out, no intermediate directories are created. These are useful on their own, and are probably the most widely used form of module. For example, if I have users who only access the documentation in a project, I can create a module

     docs project/src/docs

When users checkout the docs module, they will only get the docs directory and the files and directories beneath it.

Ampersand modules - ampersand modules are the last piece of the puzzle, ampersand modules allow us to accumulate other modules together under one name. For example

     docsproject &docs

When a user checks out the docsproject module, they will get a docsproject directory with a docs subdirectory.

For example, say I have an existing J2EE project in a CVS module called project. When checked out, it looks like the following:

     /project

       /conf

          /web

       /src

       /jsp

I want to reorganize this so that I can develop with my files in an exploded EAR format so that I can point my application server at a directory and have it hot-deploy JSPs and changed classes. So I would rather have my project look like this:

     /newproject (root location)

       /ear (the directory to hot deploy)

          /web (the web app root)

             /WEB-INF (the configuration info for the webapp)

       /src (the application src)

How can I do this with CVS modules? Add something based on the following to your CVSROOT/modules file. The idea here is that we will use regular modules to build links to the key directories in our repository that we want to pull out, use -d when necessary to move directories "down", then we will use ampersand modules to reassemble them into a new tree. We can also exploit module options here, in particular -d, which allows us to rename the working directory for a module to something other than the module name, and !, which allows us to exclude files or directories from a module.

  web project/jsp                           #create a regular module pointing to a sub dir

  WEB-INF -d web/WEB-INF project/conf/web   #create an alias called WEB-INF for the directory project/conf/web, that when checked out, 

                                            #goes into a directory called web/WEB-INF

  ear &web &WEB-INF                         #create a module called ear that contains web and WEB-INF

  src project/src                           #create a module for src to allow use to use it in an ampersand module

  newproject &ear &src                      #put both the ear and src module under a new name called newproject

Now when a user checks out the module newproject, they will get the following directory tree:

/newproject

  /src (from the src module)

  /ear (from the ear ampersand module)

     /web (from the web module)

        /WEB-INF

Advantages

There are a numer of advantages to using this approach: repository history is preserved, existing build and deploy scripts that depend on the old layout continue to work, and users can gradually be transitioned to the new layout. Of course, there are risks in supporting 2 layouts, even temporarily, since minor differences between the builds can hide errors.

Limitations

One of the limitations to note with CVS modules is that modules do not know that they contain other modules do like true directories in CVS. What does this mean? If you delete the src directory from the above tree and run cvs up -d you will not get the src directory.

     Monday, September 06, 2004     Off the face of the earth

Not that I've actually dropped off the face of the earth, but my wife and I just had a beautiful baby girl, and I'm lucky when I remember to tie my shoes. Welcome Gracie!