Introduction to Sun WorkShop

Appendix D

Source Browsing With sbquery, sb_init, and sbtags

This appendix:

• Describes sbquery, one of the command-line utilities for browsing source code
• Tells you how to work with source files where database information is stored in multiple directories
• Describes the sbtags command, which provides a quick and convenient method for collecting browsing information from source files

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 5 and the Browsing Source Code section of the online help (you can access the online help through the Help menu in any Sun WorkShop window).

The sbquery Utility

The sbquery utility provides you with a command-line browsing environment that you can access from terminals and from workstations emulating terminals. 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 The sb_init File and Commands.

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

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.

Options

To obtain a list of the sbquery command-line options, type sbquery at the shell prompt. TABLE D-1 lists and describes the options (see also the sbquery(1) man page).

TABLE D-1   sbquery Options 

Arguments	Description
-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.
-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.
-files_only	Lists only the files where the symbols you are searching for appear.
-help	Displays a synopsis of the sbquery command. Equivalent to typing sbquery with no options and no symbol.
-help_focus	Displays a list of the focus options available for querying only specific program types in a directory. Use focus options (see TABLE D-3) to issue a query limited to specific units of code such as programs or functions.
-help_filter language	Displays a list of the languages for which filter options are available for -help_filter. Displays a list of the filter options for the language for -help_filter language. Use filter options (see TABLE D-2) 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_case	Makes the query case-insensitive.
-no_source	Displays only the file name and line number associated with each match and not the source line containing the match.
-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 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.
-symbols_only	Displays a list of all symbols that match the patterns in your search pattern. This is useful when you use wildcards in a query.
-version	Displays the current version number.
-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 the sh(1) man page 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	Uses only literal strings and does not use any wildcard expressions for the query. This is 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 described in TABLE D-2 and focus options described in TABLE D-3.

The filter options 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

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	Limits query to matches in program.
-in_directory directory	Limits query to matches in directory.
-in_source_file source-file	Limits query to matches in source-file.
-in_function function	Limits query to matches in function.
-in_class class	Limits query to matches in class.
-in_template template	Limits query to matches in template.
-in_language language	Limits 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 source browsing in Sun WorkShop).

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 sun_source_browser.ex file.
SUNPRO_SB_INIT_FILE_NAME	The absolute path name of the sb_init file. For more information on sb_init, see The sb_init File and Commands.

The sb_init File and Commands

This section describes how to work with source files where 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.

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 SunWS_config directory, which 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.

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.

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

TABLE D-5   sb_init Commands

Comand	Description
import	Reads databases in directories other than the current working directory.
export	Writes database component files associated with specified source files to directories other than the current working directory of the compiler. This command also acts as an import command.
replacepath	Specifies how to modify paths to file names found in the database, allowing you to move a database.
automount-prefix	Enables you to browse source files on a machine other than the one on which you compiled your program.
cleanup-delay	Limits the time elapsed between rebuilding the index and the associated database garbage collection.

import

% import pathname

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.

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.

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); 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 with 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 one of the following:

• Ensure that all source files are mounted at the same mount point on all machines.
• Compile your programs in an automounted path. A reference to such a path causes the automounter to automatically mount a file system from another machine.

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.

The sbtags Utility

The sbtags command provides a method for collecting browsing information from source files, enabling you to collect minimal browsing information for programs that do not compile completely. See also the sbtags(1) man page.

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:

• Cannot issue queries about local variables
• Cannot browse classes
• Cannot graph class relationships
• Has limited ability to issue complex queries
• Has limited ability to focus queries
• Has less reliability than compiled information

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 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:

• Class Browser and Class Graph features are not available.
• The database does not contain information on all symbols and strings. It contains information on functions, classes, types, and calls to functions.
• Time is saved since the sbtags program runs faster than the compiler.
• The database size is much smaller than the size of your source code.
• The database content is not guaranteed to be semantically correct because the sbtags program performs only simple syntactic and semantic analysis and may sometimes be in error.
• A database is generated even if the source code cannot be compiled because the code is incomplete or semantically incorrect.

To generate a browsing database using sbtags, type the following at a command line:

% sbtags file

file is the file for which you want to generate the database. See the sbtags(1) man page for more information.