Command Line Processing

## Using "undc"

A project database file (.udc) is created when a project is configured and analyzed using either the graphical interface of Understand for C++ or the command line tool "undc".

The "undc" command line takes this form:

undc [-db] db [files] [Options]

where

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

Refer to the following sections for details on all the available command line options and how to create and analyze a project.

### Command Line Options

The only required argument for all commands using "undc" is the project database file.

Following are the optional command line options for "undc".

Refer to the following sections for examples on using "undc" to create and analyze a project.

option | description
--- | ---

-add [files] -add @filelist.txt

Add the list of files to the existing project. Files can be specified in two ways: individually, separated by spaces, or in a text file, with one file per line. For example -add *.h *.c will add all .c and .h files in the current directory to the project. Or use -add @filelist.txt to add all files that are listed in the filelist.txt file to the project. May be used multiple times on the same command line.

-create [project file] | Create a new project.
-define definition @definitionfile | Defines a macro which is then saved to the project database for subsequent runs. This is an optional argument which may be used multiple times on the same command line. A definition prefaced by @ may be used to specify a file that contains macro definitions of the form: #define foo bar foo=bar foo bar which all define a macro "foo" as "bar"
-delete files | Delete the list of files from the existing project. Separate multiple files with spaces.
-include includes @includes | An optional argument to add a path to the analysis include path. This include path will be saved in your project database file. This argument may be specified multiple times on the same command line A file prefaced by @ can be used to list include directories (one per line)..
-list | Outputs to the screen the list of source files configured in the project.
-quiet | Use for quiet processing, i.e. status messages will not be written to the screen. This argument is optional. By default, some status messages are written to the screen.
-rebuild | Performs a full reparse of all project source files whether they have been modified or not.
-refresh | Performs an incremental reparse of the project source files. Only modified and dependent files are re-parsed. This is the default action when no other option is specified. If project parameters have changed since the last build, be sure to use -rebuild instead of -refresh.
-verbose | Use for verbose processing, i.e. status messages will be written to the screen. This argument is optional.

### Creating a New Project

There are several ways to create a new project file using "undc". Of course you can use the graphical interface of Understand for C++ to first create your project, but here we will examine a few ways to do it from the command line.

To create a new, empty, project called sample.udc:

undc -create -db sample.udc

Then you may add files to the project. To add all .c and .h files in the current directory to your project:

undc -db sample.udc -add *.c *.h

Or you can create a text file listing all your source files (one file per line) and use that file to load your project. Entries in the list.txt file may look something like this:

c:\sti\sample\understand_c\fastgrep\egrep.c
c:\sti\sample\understand_c\fastgrep\regerror.c
c:\sti\sample\understand_c\fastgrep\regexp.c
c:\sti\sample\understand_c\fastgrep\strpbrk.c
c:\sti\sample\understand_c\fastgrep\regexp.h
c:\sti\sample\understand_c\fastgrep\regmagic.h

Then reference the file to add those source files to your project:

undc -db sample.udc -add @list.txt

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

undc -db sample.udc -create -add *.c *.h

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

### Analyzing a Project

The "undc" command line program allows you to analyze (or re-analyze) a previously created project database. Refer to the preceding section if you haven't yet created and configured your project.

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:

undc sample.udc -rebuild

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

undc sample.udc -refresh

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