Command Line Processing

prevnext

Creating and Parsing a Database with undada


A command line tool for creating and building Understand for Ada databases is undada. It is a command line program that parses your Ada 83 or Ada 95 source code to populate the database with information that can be browsed or reported on.

The "undada" command line takes this form:

undada -db database [-create_83|-create_95] [files] [options]

where

db is the project database file and is a required argument.

Create a new database with the -create_83 or -create_95 option and then load the files into the database with the -add option. To parse all files, specify -rebuild. Once the database is initially populated, subsequent parsing can be incremental, meaning that a file only needs to be re-parsed when it has changed, or something it depends on changes. For this incremental parsing, specify -refresh.

The command line options for undada are:

Option Explanation
-a file [files] -a @listfile -add file [files] -add @listfile Specify one or more files to add to the database. Wildcards are expanded by the command shell. Files can be specified in two ways: individually, separated by spaces, or in a text file, with one file per line. For example -add *.ads *.adb will add all .ads and .adb files in the current directory to the project. Or use -add @filelist.txt to add all files that are listed in the listfile to the project. The listfile contains one file per line. Full or relative paths may be used. A # sign in the first column of a line in the listfile indicates a comment. May be used multiple times on the same command line.
-create_83 -create_95 Specify either the Ada83 or Ada95 language when creating a new database. This cannot be changed once the database is created. Creating a new database will overwrite an existing database of the same name.
-db database Specify name of database. An extension of .uda is provided if no extension is given.
-d file [files] -d @filelist.txt -delete file [files] -delete @filelist.txt Specify one or more files to delete from the database. Wildcards are expanded by the command shell. Files can be specified in two ways: individually, separated by spaces, or in a text file, with one file per line. For example -delete *.ads *.adb will remove all .ads and .adb files in the current directory from the project. Or use -delete @filelist.txt to delete all files that are listed in the listfile from the project. The listfile contains one file per line. Full or relative paths may be used. A # sign in the first column of a line in the listfile indicates a comment. May be used multiple times on the same command line.
-error error_file Specify where error messages should be logged to. If omitted then errors are sent to the standard error.
-h -help Show the command line options.
-libunit_defs [before | after | both | none] If comment association is turned on then this option tells where to collect comments from for top level library units (e.g. package, separates, etc...). Before indicates before the definition but after last definition. After indicates after definition but before next. After is the default.
-list [ordered] [status] Lists files in the project. Also specify status to report current status of file: "Okay" if current or "Changed" if file has been modified since last parse. Specify ordered to also include ordered list of errors and warnings reported during analysis.
-nestunit_defs [before | after | both | none] Similar to -libunit_defs only for nested program units. These may have a different commenting convention. After is the default.
-quiet Does not output any messages to standard output.
-rebuild Reparses all source files in the project.
-refresh Bring the database up to date by parsing files that have changed and the files that they affect.
-standard directorypath Optional. Specifies path where source for Ada standard library resides. Use to override standard library provided with Understand and to specify alternate if your compiler uses an alternate standard.. Only valid in conjunction with -create_83 or -create_95.
-typeobject_defs [before | after |both | none] Similar to -libunit_defs but controls comment association for types and objects. After is the default.
-verbose Print descriptions of what is happening to standard output. -v may be used as well.

The following sections show example uses of undada.

Example: Create an Ada 95 Database

This example creates a database populated with the Standard library for Ada 95:

undada -create_95 -db myproject

The resulting database, myproject.uda, can then be used in the analysis of Ada 95 source code.

Use -create_83 instead of -create_95 if you have entirely Ada 83 source code. Use -create_95 if you have a mixed Ada 93/Ada 95 project.

Tip: To save space, specify the Ada 83 option if you have only Ada 83 code. The Ada 95 library is six times larger.

Example: Processing all files in a directory

If you have a small amount of source files then it may be easiest to just supply their names to the analyzer using the wildcarding abilities of your operating system shell. In this example we will process all Ada specification files (.ads) and Ada body files (.adb):

undada -db myproject -add *.ads *.adb

Example: Creating and Processing a list of files

Note that in some cases there maybe too many files to use the -files technique. A common command line limitation is 255 characters. A directory with hundreds or thousands of files may easily exceed this limit. In this case, or when you want more fine-grained/repeatable control over what files are processed, then you should create a "process list file". This file, the format of which is one filename per line:

myproject.ads
myproject.adb
mainpackage.adb

is processed via the -add command line option:

undada -db myproject -add @myproject_files.lst

Note that there is no limit on the number of files listed in the list file.

On Unix here are a couple ways to create such a file:

- use the `ls' command, as in
ls *.ads *.adb *.sep > my_project.lst
- use the `find' command to recurse sub-directories, as in
find . -name "*.ads *.adb *.sep" -print > my_project.lst

In a Windows NT/95 command shell:

- use the dir command with the /b option:
dir /b *.ads *.adb > my_project.lst
- use the /s option to recurse sub-directories, as in
dir /b /s *.ads *.adb > my_project.lst

Example: Creating a database and adding sources all in one-step

Alternatively, you can create and add files to the database all in one command. For example:

undada -db myproject.uda -create_83 -add *.ads *.adb

Whatever way you choose to create your project database, you are now ready to analyze that project.

Example: Analysis: Refresh vs Rebuild

When analyzing a project, you have two options to choose from. You may re-analyze all files with the -rebuild option, or only those files that have changed with the -refresh option.

If you are doing your first analysis after creating a new project, it doesn't matter which option you choose as it will parse all files regardless. However, if you are performing this function on a regular basis, you may prefer to do an incremental analysis where only the modified files and any other files dependent on those files are re-analyzed.

For example. parse all files in the project with the following command:

undada -db myproject.uda -rebuild

Or, to perform an incremental analysis, re-parsing only those files that have changed or other dependent files, use the command:

undada -db myproject.uda -refresh

Example: Keeping a database up to date

Once you have successfully parsed your code for the first time, keeping the database up to date is simple:

undada -db myproject.uda -refresh

will check each file previously parsed into the repository to see if it has changed. If it has changed then it will re-parse it, and any files that depend on it (and so on) until the database is fully refreshed.

Use this feature to keep your database up to date while keeping your parsing to a minimum.

Example: Using Libraries to Partition Analysis

Suppose you have 3 separate areas in my project:

- Radar
- Avionics
- Test and Support

Ideally you would like to create a repository matching the structure of your software, thus permitting you to have reports of your whole system, or of each individual system.

An example way to accomplish this is to create a database, and to use undada three times - once for each partition. For instance:

undada -create_83 -db myproject
undada -db myproject -add @avionics.lst -l avionics
undada -db myproject -add @radar.lst -l radar
undada -db myproject -add @test_support.lst -l test_support

This creates a database that has 4 library partitions in it, Standard (there when you started), Radar, Avionics, and Test_Support. These libraries can then be browsed separately, or in combination. Reports can also be constrained as well.

prevnext


Scientific Toolworks, Inc.
http://www.scitools.com
Voice: (802) 763-2995
Fax: (802) 763-3066
support@scitools.com
sales@scitools.com