Using CDB

This section covers the basic operations of CDB. Using CDB typically translates into seven steps, which you need to repeat for different versions of the code:

1. Build GCCXML Package (GXP) files for the source code you wish to modify

2. Extract the source code data from the GXP files into a database

3. Modify your code as required

4. Build GXP files for the modified code

5. Extract the modified source code data from the new GXP files into a second database

6. Compare the two databases to check compatibility

7. Clean up all files that were created.

The tool represents each set of binaries as configurations in the attached local database. You need to provide a name to a configuration set, so that the same name can be used while comparing two sets of the configuration data. The database is maintained by the tool and requires no administration. Once the configuration has been built up, you need to run the Symbian OS build tools.

CDB operates on files called GCCXML Packages (GXPs). A GXP contains XML-formatted debugging information about the source code, the relevant .def files, and an XML-formatted representation of the .mmp file. These files are used to build the source. For more information on GCCXML files, see GCCXML build target.

Build GXP for a component invoking the command:

abld build gccxml

This is the same as building a component using abld build winscw for CodeWarrior^TM. GXP files are built into epoc32\release\gccxml.

While extracting, the data is usually extracted from GXP files that are found in epoc32\release\gccxml\urel. So, GXP files should be built to this location. For each component you wish to compare, run abld build gccxml urel command to create the relevant files. When you get a new EPOC, GXP files are not included in the EPOC tree by default.

CDB has two major modes of operation:

1. extraction

2. comparison

In the extraction phase, the CDB reads a series of GXP files. The data required to perform the analysis is added to the specific database. The extraction is associated with a configuration which corresponds to an OS release. This release is identified by a version and a build number. The data extracted can be referred to as 'configuration' and will have a name associated with it.

The following is an example command to extract the GXPs into the database:

> cdb –d p:\epoc32\data\cdb.db extractrelease comp_old 

This command extracts the data related to the old component into a configuration called comp_old, which is located in the first database at P:\\epoc32\data\cdb.db. Similarly, you need to extract the data related to the modified component into the second database. For more details on this command, see CDB commands.

In the comparison phase, the CDB compares the data contained in the two databases for any BC breaks.

The following is an example command to compare two releases:

> cdb –d p:\epoc32\data\cdb.db comparerelease comp_old -a q:\epoc32\data\cdb.db comp_new -r e:\Report_Test.xml

This command will compare the release called comp_old which is located in p:\epoc32\data\cdb.db with the release called comp_new, which is located in q:\epoc32\data\cdb.db. –r option indicates that the resultant report should be called Report_Test.xml and should be stored in the directory e:\\. The report will be generated in both XML and HTML formats so that the machine and human can read them easily. Refer Generating reports, for more details. For more information on the comparerelease command, see CDB commands.

When databases are no longer needed, delete the two databases manually from their directories.