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 GXP files for the source code you wish to modify

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

3. Modify your code as required

4. Build GXP files for the modified code

5. Extract the data about the modified code 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 set of configuration, so that the same name can be used while comparing the 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 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 same as building a component using abld build winscw for CodeWarrior^TM. GXP files are built into epoc32\release\gccxml.

While extraction, 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 using CDB, you need to perform an abld build gccxml urel command to create the relevant files. GXP files are not included in the EPOC tree by default, when you get a new EPOC.

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 a release of the OS. 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 command to extract the GXPs into the database would look like this:

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

This command extracts the data about the old component into a configuration called comp_old which resides in the first database at P:\\epoc32\data\cdb.db. In the similar way you need to extract the data about 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 command to compare the two releases would look like this:

> 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 can be found in p:\epoc32\data\cdb.db with the release called comp_new, which can be found in q:\epoc32\data\cdb.db. –r 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.