test

Using Sun WorkShop

Appendix D Browsing Source With sbquery, sb_init, and sbtags

This appendix:

The information in this chapter pertains mainly to the use of the command line to complete tasks also available from within Sun WorkShop. For more conceptual information on using source browsing, see Chapter 3, Browsing Source Code" and the Sun WorkShop online help.

This appendix is organized into the following sections:

Browsing Source With sbquery

The sbquery command provides you with a command-line browsing environment that you can access from terminals and from workstations emulating terminals.

Understanding sbquery

The command-line interface to the Source Browsing mode of Sun WorkShop is sbquery.

To issue a query from the command line, type sbquery, followed by any command-line options and their arguments, followed by the symbol you want to search for:

sbquery [options] symbols

All lines that contain symbols are displayed.

sbquery displays a list of matches that includes the file in which the symbol appears, the line number, the function containing the symbol, and the source line containing the symbol.

By default, sbquery searches for symbols in the database in the current working directory. If you want to browse a database stored in another directory, see "Controlling the Browser Database With sb_init".

Command Reference

To obtain a list of the sbquery command-line options, type sbquery at the shell prompt. Table D-1 lists and describes the options.

Table D-1 sbquery Options

Arguments 

Description 

-break_lock

Breaks the lock on a locked database. This argument might be needed if the update of the index file is aborted. The next time you issue a query you might get a message telling you that the database is locked.  

After using this option, your database may be in an inconsistent state. To ensure consistency, remove the database directory and recompile your program.  

-help

Displays a synopsis of the sbquery command. Equivalent to typing sbquery with no options.

-help_focus

Displays a list of the focus options available for querying only specific program types in a directory. Use focus options to issue a query limited to specific units of code such as programs or functions.  

-help_filter

Displays a list of the languages for which filter options are available. Use filtering options to search for symbols based on how they are used in a program. 

max_memory size

Sets the approximate amount of memory, in megabytes, that should be allocated before sbquery uses temporary files when building the index file.

-no_update

Does not rebuild the index file when you issue a query following compilation. If you do not include this option and issue a query following compilation or recompilation, then the database updates and processes your query.  

-o file

Sends query output to a file. 

-show_db_dirs

Lists all database directories scanned when you issue a query. The list includes the following: 

the database directory in the current working directory and all other database directories specified by the import or export commands in your sb_init file.

-version | -V

Displays the current version number. 

-files_only

Lists only the files where the symbols you are searching for appear. 

-no_secondaries

Returns only the primary match. A secondary match is an identifier inside a macro. You might want to turn off secondary matches if you are doing a lot of filtered querying, and the symbols you are querying on are used in a lot of macros. 

-no_source

Displays only the file name and line number associated with each match. 

-symbols_only

Displays a list of all symbols that match the patterns in your search pattern. Useful when you use wildcards in a query.  

-pattern symbol

Queries on symbol, which may contain special characters, including a leading dash (-). This option allows you to query on a symbol that looks like a command-line option. For instance, you can query on the symbol -help, and sbquery distinguishes it from the regular option -help.

-no_case

Makes the query case-insensitive. 

-sh_pattern

Uses shell-style expressions when issuing a query that includes wildcards. This wildcard setting is the default; include this option if you are doing other pattern matching on the same command line. 

See sh(1) for more information about shell-style pattern matching.

-reg_expr

Uses regular expressions when issuing a query that includes wildcards. If you do not include this option, shell-style patterns are assumed. 

-literal

Does not use any wildcard expressions for the query. Useful when you want to search for a string that contains meta characters from other wildcard schemes. 

Two types of options are available to help you narrow your search: filter options (see Table D-2) and focus options (see Table D-3.)

Filter Language Options

The filter options listed in Table D-2 are used to search for symbols based on how they are used in a program. For example, you could limit your search to declarations of variables. 

sbquery -help_filter language

Table D-2 Filter Language Options

Filter Option 

 Description

ansi_c

 C

sun_as

 Assembly language

sun_c_plus_plus

 C++

sun_f77

 FORTRAN 77

sun_f90

 Fortran 90

Focus Options

The focus options listed in Table D-3 limit your search to specific classes of code, such as particular programs, functions, or libraries. 

sbquery focus_option symbol

Table D-3 Focus Options

Focus Option 

Description 

-in_program program

Limit query to matches in program.

-in_directory directory

Limit query to matches in directory.

-in_source_file source_file

Limit query to matches in source_file.

-in_function function

Limit query to matches in function.

-in_class class

Limit query to matches in class.

-in_template template

Limit query to matches in template.

-in_language language

Limit query to matches in language.

Note -

If you include two or more focus options, a match is returned if it is found with any of the supplied focus options.

Environment Variables

Environment variables provide information that affects the operation of sbquery (and of source browsing in Sun WorkShop). For more information on sb_init, see "Controlling the Browser Database With sb_init"."

Table D-4 Environment Variables

Variable 

Description 

HOME

The name of your login directory 

PWD

The full path name of the current directory 

SUNPRO_SB_ATTEMPTS_MAX

The maximum number of times the index builder tries to access a locked database 

SUNPRO_SB_EX_FILE_NAME

The absolute path name of the file sun_source_browser.ex

SUNPRO_SB_INIT_FILE_NAME

The absolute path name of the sb_init file

Controlling the Browser Database With sb_init

This section describes how to work with source files whose database information is stored in multiple directories. As a default, the database is built in the current working directory and searches that database when you issue a query.

Understanding sb_init

The text file sb_init is used by the Source Browsing mode of Sun WorkShop, the compilers, and sbtags to obtain control information about the source browsing database structure. Use sb_init if you want to work with source files whose database information is stored in multiple directories.

The sb_init file should be placed in the directory from which source browsing, the compilers, and sbtags are run. These tools look in the current working directory for the sb_init file.

Moving the sb_init File

The default is to look in the current working directory for the sb_init file. To instruct Sun WorkShop and the compiler to search for the sb_init file in another directory, set the environment variable SUNPRO_SB_INIT_FILE_NAME to /absolute/pathname/sb_init.

File Commands

To use an sb_init command, add the command to the file. The sb_init file is limited to the following commands:

Command Reference

import 

import /pathname
 to directory

This command allows the Source Browsing mode of Sun WorkShop to read databases in directories other than the current working directory. Use of the import command enables you to retain separate databases for separate directories.

For example, you may want to set up administrative boundaries so that programmers working on Project A cannot write into directories for Project B and vice versa. In that case, Project A and Project B each need to maintain their own databases, both of which can then be read but not written by programmers working on the other project.

In Figure D-1, the current working directory is /project/source1. The database in source2 is read by including either of these commands in the source1 sb_init file: 

import /project/source2
import ../source2

Figure D-1 import Example

Graphic

export 

export prefix 
into path

This command causes the compilers and sbtags to write database component files associated with source files to directories other than the current working directory used by the Source Browsing mode of Sun WorkShop and the compiler.

Whenever the compiler processes a source file whose absolute path starts with prefix, the resulting browser database (.bd) file is stored in path.

The export command contains an implied import command of path, so that exported database components are automatically read by the Source Browsing mode of Sun WorkShop.

The export command enables you to save disk space by placing database files associated with identical files, such as #include files from /usr/include, in a single database, while still retaining distinct databases for individual projects.

If your sb_init files include multiple export commands, then you must arrange them from the most specific to the least specific. The compiler scans export commands in the same order that it encounters them in the sb_init file.

In Figure D-2, to place the .bd file and index file created for files from /usr/include in a database subdirectory in the sys subdirectory, the user included this export command in the sb_init file for source1: 

export /usr/include into /project/sys

Figure D-2 export Example 1

Graphic

If the configuration had included a source2 directory with a sb_init file containing the same export command, then you would save disk space because you did not create two identical database files. For the stdio.h files, the compiler would create a single database file for stdio.h in the sys subdirectory.

The sb_init file contains an implied export/into. command that instructs the compiler to put database files created for source files not explicitly mentioned by an export command in the current working directory. In Figure D-2, the .bd files associated with a.cc and b.cc are placed in the database subdirectory in the source1 directory.

When you include the export command in the sb_init file, an implied import command causes the specified database to be read. Given the configuration in Figure D-2, the database in the sys subdirectory, as well as the database in the source1 directory, is searched each time you issue a query.

As another example, suppose the user included this export command in the sb_init file for source1: 

export /project/include into /project/include

As shown in Figure D-3, this places the database files and index file created for files from /project/include in the database subdirectory in the /project/include subdirectory. An implied import command caused the database in /project/include to be read.

Figure D-3 export Example 2

Graphic

The database files are stored in a common subdirectory even though the command located the include file in a nonstandard location. The export command saves disk space if the project includes multiple references from many different directories to the same include file.

replacepath 

replacepath from_prefix   to_prefix

This command specifies how to modify path names in the source browsing database.

In general, from-prefix corresponds to the automounter "mount point" (the path name where the automounter actually mounts the file system); and to-prefix corresponds to the automounter "trigger point" (the path name known and used by the developer).

There is considerable flexibility in how an automounter is used; the method can vary from host to host.

Path replacement rules are matched in the order that they are found and matching stops after a replacement is done.

The default replacepath command is used to strip away automounter artifacts: 

replacepath /tmp_mnt

When used for this purpose, the command should be given as the mount point as the first argument and the trigger point as the second argument.

automount-prefix 

automount-prefix mount_point  trigger_point

The automount-prefix command enables you to browse on a machine other than the one on which you compiled your program. This command is identical to the replacepath command except that automount-prefix path translations occur at compile time and are written into the database.

The automount-prefix command defines which automounter prefixes to remove from the source names stored in the database. The directory under which the automounter mounts the file systems is the mount_point; the trigger_point is the prefix you use to access the exported file system. The default is /.

If the path in the database fails, the path translations from both commands (that is, automount_prefix and replacepath) are used to search for source files while browsing.

At first glance, searching both paths may not seem possible; the browser database that is created when you run the compiler contains the absolute path for each source file. If the absolute path is not uniform across machines, then Sun WorkShop will not be able to display the source files when it responds to a query.

To get around this problem, you can do either of the following:

There is a default automount-prefix command that is used to strip away automounter artifacts: 

automount-prefix /tmp_mnt
 /

The default rule is generated only if no automount-prefix commands are specified.

For more information on using the automounter, see the automount(1M) man page.

cleanup-delay

This command limits the time elapsed between rebuilding the index and the associated database garbage collection. The compilers automatically invoke sbcleanup if the limit is exceeded. The default value is 12 hours.

Collecting Browsing Information With sbtags

The sbtags command provides a quick and convenient method for collecting browsing information from source files, enabling you to collect minimal browsing information for programs that do not compile completely.

Understanding sbtags

The sbtags command collects a subset of the information available through compilation. The reduced information restricts some browsing functionality. A database generated by sbtags enables you to perform queries on functions and variables and to display the function call graph.

A tags database:

Once a file has been changed, it often need not be scanned again to incorporate changes into the database.

An sbtags database is based on a lexical analysis of the source file. Though it does not always correctly identify all the language constructs, it will operate on files that will not compile and is faster than recompilation.

sbtags recognizes definitions for variables, types, and functions. It also collects information on function calls. No other information is collected (in particular, other semantic information for complex queries is not collected).

The functionality of sbtags is similar to ctags and etags, except for the Call Grapher information. You may mix direct queries to the database for definitions and graphing with pattern-matching queries.

With an sbtags generated database:

Generating an sbtags Database

To generate a browsing database using sbtags , type sbtags , followed by the name of the file (or files) for which you want to generate the database:

sbtags file ...