Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Using AURA

Using AURA typically translates into four steps:

  1. Get and store information about the APIs of the system for which the application has been developed.

  2. Build the EDG reports for the application which uses the Symbian OS APIs.

  3. Parse the EDG report files, analyse and store the Symbian OS API data in the database.

  4. Generate the analysed Symbian OS API usage reports for an application.

Each of these steps are discussed in detail in the following sections.

Note the following restriction on using AURA: the application (source code) to be analysed must be on the same drive as the EPOC32 being used. You should run all the AURA define commands from this drive.


Parsing and storing the Symbian OS API information

AURA can process a Symbian APIs classification file for each build to which the component under analysis belongs. For example, imrep_M04045_Symbian_OS_v9.3.xml, the Symbian API classification file for build number M04045.

Note: You should provide the Symbian API classification file of the build for the component under analysis as input to AURA.

AURA parses this API classification file, and produces a new database to store the parsed information. You can stop parsing and stop the creation of the database if the input API classification file is not a valid document.

aura define -a < API file >

This command extracts the data into the database that is created for the specified build. Using appropriate options you can specify the path to the API classification file. For more details on the command, see AURA commands.

For example:

aura define -a E:\AURA\imrep_03821_Symbian_OS_v9.3.xml

This command first tries to connect to the default database, aura.db that is specified in aura.properties file. If the database already exists in the specified location, you need to delete the existing database files (aura.db.* files) from the specified database location before trying to fill the database with new im report (interface management report) information.

If the database does not exist, it creates a new database. It then parses the API classification document that is specified in -a option. The command then stores the API items used in the build and their classification information into the database. The imrep file (API classification document) contains the details of the access and the status of APIs of a Symbian OS build.

Note: The build number of the build that generated the API classification document (for example, imrep_M04045_Symbian_OS_v9.3.xml) should match with the build number (for example, M04045) of the analysed component (source code).

The following diagram shows the process of storing the build's API information using define command.

Storing the API information of a Symbian...

Storing the API information of a Symbian OS build.

For more information on how the data is stored in the database, see AURA database.

[Top]


Building the application

To get the report on an application's APIs, you need to first build the application on the edg platform. This generates two text files. The first text file contains a list of paths to API report files (*.cpp.aut) and the second text file contains the path to the system include files used in the application. You can use these files as input to AURA. AURA parses them and updates the existing database of Symbian API items.

To build an application for the edg platform, use the following command:

bldmake bldfiles 
abld build edg urel

The build process generates the EDG reports for all the source files. For more information on EDG, see EDG files. When the application is built without specifying the build platform (for example, urel or udeb) the edg build process generates three text files for urel edg reports, udeb edg reports and for system include paths.

The following diagram show the work flow to store the application's API information:

Parsing and storing the EDG reports

Parsing and storing the EDG reports

[Top]


Parsing the EDG reports and comparing the API data

Run the following command to parse the EDG reports and populate the database related to the application:

aura define 
-e < API report list file > 
-I < Include list file >   

where, -e specifies the full path to the EDG_UREL_REP_LIST.txt file containing the list of API information, and -I the full path to the EDG_SYSINC_LIST.txt file containing the list of system include files. The files are located in a sub-directory of the epoc32\build directory.

For example:

aura define 
-e E:\epoc32\build\work\STAT\Device\group\EDG_UREL_REP_LIST.txt 
-I E:\epoc32\build\work\STAT\Device\group\EDG_SYSINC_LIST.txt

This adds the Symbian OS APIs that are used in the application to the database for each of the EDG report produced.

[Top]


Generating reports

The next step is to use AURA to analyse and report on the data that has been input. The report contains information about the Symbian OS API items that are used in the application and their interface management classification details. Note that only Symbian OS APIs are reported. APIs defined by licensee platforms are not reported.

To generate a report run the following command:

 aura apianalyse [-r report]

You can restrict the report by specifying interface management access levels using the -f option. For example:

aura apianalyse -r d:\aura_report.xml -f internalAll

The command produces an XML report and an easy-to-read HTML report. The HTML report is produced from the XML report using a style sheet specified in the properties file.

[Top]


XML report

The XML report generated by AURA will look like the following:

[Top]


Providing data integrity

AURA generates a unique checksum number for a report to protect the integrity of the data contained in it. When a report is modified, a new checksum number is generated. The new number for the same report shows that the original report is altered. This helps in detecting any accidental alterations in the report.

[Top]


See also

AURA database