Hacking Guide

This guide is intended for those who want to contribute to the development of eccvs(Easy Concurrent Versions System). Throughout this document, the (would be) contributors are referred as developers.

This document assumes that the developers do have some working experience with the eccvs. We believe that "only an effective user can become a developer". So before contributing to the development of eccvs, please try to use it. Click here to download eccvs.

Table Of Contents

1. Architecture

2. Abstract Interfaces

3. Implementation

4. Specification Documents

5. TODO

1. Architecture

As shown in the above diagram, the entire architecture is roughly divided into five modules and each module has its own well defined purpose.

1. Main Module

The main user interface module is nothing but the overall GUI which comprises of the menus, tool bars, status bar, a working copy browser (similar to file browser), preferences, etc.,

The main purpose of this module is to enable an user to interact with the application. The working copy browser displays the content of any working copy. It can be visualized as a mini-nautilus file browser. The browser is capable of displaying different emblems for different CVS file types.

2. Input Module

There are quite a lot of version control mechanisms that are offered by any version control system. This include checkout, commit, update, etc., We refer these mechanisms as functionalities. Each functionality requires some input from the user to execute the operation.

The purpose of this input module is to get the functionality specific input from the user. Each functionality will have its own input module/class.

3. CvsInterface module

The CvsInterface module is responsible for executing the desired CVS operation. It uses the cvsgui-protocol which is the part cvsgui project.

4. Parser Module

The output produced by the CVS process/command is parsed by this parser module. It packs the parsed output and gives it to the caller. Each functionality will have its own parser.

5. Output Module

This module displays the output produced by the parser.

2. Abstract Interfaces

Before getting into the details of the abstract classes/interfaces, we need to be familiar with the executeCmd() function. The following algorithm serves this purpose.

One important note about the above explained algorithm is that it does not depend on any specific CVS functionality. It uses the abstract-interfaces of Input (EccvsInput) and Parser (EccvsParser) classes to achieve the purpose. We can simply pass the references of any functionality specific (like checkout, commit, etc.,) Input & Parser objects and the executeCmd() will do the rest.

The above mentioned algorithm is possible if and only if the functionality specific classes (Input & Parser) are derived from the abstract classes. For example, EccvsCheckoutInput class should be derived from EccvsInput and EccvsCheckoutParser class should be derived from EccvsParser (in case of checkout functionality).

1. EccvsInput:

EccvsInput defines an interface which should be implemented by any functionality specific input class.

2. EccvsParser:

EccvsParser defines an interface which should be implemented by any funtionality specific parser class.

For example, consider that we need to add "checkout" functionality to eccvs. To do this:

1. Define EccvsCheckoutInput which should be derived from EccvsInput. Implement all the abstract methods.

2. Define EccvsCheckoutParser which should be derived from EccvsParser. Implement all the abstract methods.

3. Instantiate the objects from EccvsCheckoutInput, EccvsCheckoutParser and EccvsOutput classes and call the executeCmd(..reference of the objects..) to execute the functionality. [This code should be placed in the event callback that triggers the functionality]

3. Implementation

eccvs is being implemented in C and C++. It uses gtk-2.6, libgnomeui-2.0.0, gnome-vfs-2.0.0 and libglade-2.0.0.

MainUI module:

The main user interface module uses the GtkAction based menus and tool bars rather than the Gnome menu systems. GtkIconView (introduced in gtk-2.6.0) widget is used for implementing the working copy browser.

Parser module:

Actual parsers are developed using LEX and YACC. The Eccvs*Parser classes are wrappers for this YACC generated parser.

Look into eccvs-checkout-parser.yy, eccvs-checkout-lexer.ll, eccvs-parser.h, eccvs-parser.cpp, eccvs-checkout.h and eccvs-checkout.cpp files to know more about the implementation details of parsers.

[LEX & YACC may seem unnecessary for these simple parsers but they will be helpful for future enhancements]

Directory structure:

								
eccvs/
  |
  + cvsunix/ - the patched cvs code (obtained from gcvs and modified)
  |
  + extern/ - cvsgui-protocol and other external libraries
  |
  + pixmaps/ - icons and emblems
  |
  + po/ - for i18n support (needs help, we are not familiar with this)
  |
  + src/ - the source code
  |
  + ui/ - UI related files (UI XML description and GLADE files)
  |
  [files] - autotools related files

					

4. Specification documents

This project does have SRS (Software Requirements Specification) and SDS (Software Design Specification). These documents may also help you to understand eccvs in a better manner. SDS slightly differs from the actual implementation, but the basic concepts are same. You may need to refer these specification documents.

• Software Requirements Specification for eccvs
• Software Design Specification for eccvs

5. TODO

The following list is far from complete and it is also very abstract. See the TODO file in the eccvs source code to know more about these items.

1. Preferences dialog.
2. Functionalities except Checkout and Update.
3. Module to handle CVS repository details (.cvspass parser etc.,).
4. Browser enhancements.