Contents Previous Next Customizing Source-Navigator This chapter describes how to customize Source-Navigator to reflect your preferences. Preferences Dialog Use the Preferences dialog to specify project-specific parameters. In the Symbol Browser, from the File menu, select Project -> Project Preferences and enter your changes in the dialog. After changing any parameters in this dialog, click OK to update the project with the current settings. Note Default values may be transferred from the previously created project, some options take effect only in new windows, and some options only take effect the next time the project is opened. Project Tab of the Preferences Dialog General Project Preferences Descriptions of the general Preferences tabs (Project, Parser, Others, and Colors & Fonts) are included in this section. The following tabs are discussed in the relevant chapters: Edit see Editor Preferences. Class/Hierarchy see Class/Hierarchy Preferences. Xref see Cross-Reference Preferences. Include see Include Preferences. Version Control see Version Control Preferences. Project tab Project Read-only project Select this if the project should be read-only. Default is off. Refresh project upon startup Select this when files are likely to be changed by other developers, or when you want to be sure that your database is in sync with your sources when you start. Default is off. Changing this to on may cause delays when opening your project. For large source bases that are relatively stable, or where network latency is a problem, set this to off and periodically, from the Tools menu, select Refresh Project to resync the database with the source. Database Database directory name Source-Navigator creates all database files under this directory. If the directory already exists, you will need read and write permissions for it. If you're creating a new directory, you will need permission to create it. The file system for this directory must contain free disk space equal to the size of the source base without cross-references, and up to about ten times the size of the source code if you choose to generate cross-references. If you don't have the necessary permissions (for example, if it is a read-only file system), or if there is insufficient free disk space in your first choice of location, you may create your project directory in another location on your network by entering a directory name with its absolute path. This option can be changed only when creating a project. Permissions These buttons control the read-write permissions for your project: the first set controls access for the creator of the file, the second set for the group, and the third for "others" (everyone else on the network). Build comment database Select this to store comment strings in the database. Default is off. Database cache size Caches improve performance by using memory (fast) instead of disk (slow) where possible. Larger cache sizes increase the likelihood that data will be found in memory rather than on disk, though overallocating caches has the opposite effect. The operating system will swap the cache to disk and the system will get dramatically slower. The cache defaults are generous for most projects; don't increase them without a reason. This option can be changed only when creating a project. Enter the database cache size (in kilobytes) or accept the default value. Source-Navigator creates the project database (in the background) with the specified cache size. Increasing this amount speeds up project creation and data access, but requires that more memory be allocated to Source-Navigator. The recommended maximum is the amount of free RAM divided by 16, up to a maximum of 4 MB. The total of this amount plus the amount allocated to the cross-reference database cache should not exceed one quarter of the total memory. X-reference (Cross-Reference) database cache size Enter the Cross-Reference database cache size in kilobytes or accept the default value. Source-Navigator creates the project cross-reference database with this cache size. Increasing this amount speeds up cross-reference creation and data access but requires that more memory be allocated to Source-Navigator. This option can be changed only when creating a project. The recommended maximum size is the amount of system memory divided by 32, up to 8 MB. The total of this amount plus the amount allocated to the database cache should not exceed one quarter of the total memory. Window Split Windows: These buttons control where new views appear when you add a view to an existing window (from the Windows menu, select Add View). Select Horizontal to have new views appear to the right of the current pane; select Vertical to have new views appear below the current pane. New Windows Selecting Reusable causes new information to appear in the current window; deselecting it causes a new window to appear when you choose a new symbol, tool, or view. Selecting Keep Context causes new tool windows to be opened to the same symbol context as the current window; deselecting it causes a new tool to be empty when opened. Window size is This setting controls the size of newly-created Source-Navigator windows. You may also resize the windows after they're created. Internationalization Character set encoding This combo-box allows you to choose the character set encoding for your project to match the character set of your source files. The default character set for English, German, and most other European languages is ISO8859-1. For Japanese, the default character set is Shift-JIS. Parser tab Source-Navigator uses plug-in parsers to parse multiple programming languages. Choosing the appropriate parser is based on file extensions. Parser Tab of the Preferences Dialog Source-Navigator is pre-configured for the most commonly used file types; these can be changed and new parsers can be added. File Types and Associated Filename Extensions Parse source files as File Extensions PowerPC 601 assembly *.asm *.s *.S C/C++ *.[hHcC] *.[ch]xx *.[ch]pp *.cc *.hh *.[CH]XX *.[CH]PP *.CC *.HH COBOL *.cbl *.cob FORTRAN *.f *.for *.FOR Java *.java others *.[ly] *[IMm]akefile Tcl, [incr Tcl] *.tcl *.itcl *.itk *.tk After each of the languages is an External Editor text box; you may type in the executable (shell) command for an external editor, or you may click the "..." button to browse. If you leave the text box blank, Source-Navigator uses its built-in editor. Macro processing Macros make the task of source code analysis more complicated, and there is no single right way to handle them. By default, Source-Navigator treats them as opaque symbols and, aside from recording where they are defined, it ignores them completely. This behavior not only makes parsing substantially faster than true compilation, but it also preserves the layer of source code abstraction that is presented in the Editor. This behavior is particularly useful when maintaining software that must run on multiple platforms, and you would like to see all of the impacts that a change might have, regardless of a macro's platform definition. For some projects and/or tasks, this layer of abstraction is a barrier to code comprehension. For these cases, you can direct Source-Navigator to define and expand macros in one of four ways: define define is used to insert a symbol into Source-Navigator's preprocessor namespace. If you define FOO (or #define FOO, the leading # is optional), then conditionals that test #ifdef/#ifndef are scanned according to the #ifdef/#ifndef test. FOO will be replaced with the empty string. define can also be used to give a symbol a value (such as define FOO BAR). This will not only inject the symbol into the namespace, but will cause Source-Navigator to scan BAR whenever it sees the FOO macro. This is particularly useful for DEFUN or PROTO macros that are used to bridge between K&R and ANSI C but which otherwise are not interesting at the source code comprehension level. It is also useful when macros test numerical results, such as #if (X >= Y) or #if X. define macros can take arguments, just as in C and C++, and they can expand recursively (i.e., FOO might expand to BAR (5) which might then expand to mumble (5, 5, 0); in this case Source-Navigator would only see mumble (5, 5, 0)). replace replace is just like define, except that the symbol is not injected into the namespace. Thus, if you want to expand macros, but not have conditional code compiled away, use replace. delete Source-Navigator lets you use more than one macro file in a project. You can specify a macro in one file and then delete it from the preprocessor namespace using delete in a second macro file. undef undef doesn't do any substitution, it just affects the evaluation of #if, #ifdef, and #ifndef statements. The macro processor does not support include, token concatenation, ANSI stringification, or other pre-processor directives. These may be implemented in a future release. Defining and using macro files As explained above, Source-Navigator parses, but does not interpret, macro definitions in your project files. It only interprets macro definitions from files you specify explicitly in the parser preferences of your project. Because multiple files may be specified, you may want to organize your macro files according to global, per-user, and per-project divisions. This order is important, because Source-Navigator uses the last encountered definition for the macro. Macro files are ASCII files and every non-blank line is a macro directive. Leading blanks and # characters are stripped, and if the first character of a line is an apostrophe ( ' ), the line is treated as a comment. The macro file can contain continuation lines, for example: define ABC\ \ 5 Otherwise, the directives are interpreted as documented above. Others tab Others Tab of the Preferences Dialog Build Enter the executable (shell) command used to start your make system. HTML viewer Enter the HTML viewer to display online help. From Help, select Online Manuals to open the viewer, which must be included in your path. Bug reports Mailhost Source-Navigator supports sending bug report emails by SMTP. Enter the name of your SMTP mail server in this field. Printer ASCII Print Command Enter the command you use when printing a source file from the command line. Print Command Enter the print command appropriate for your system. For example, Linux-based systems use lpr. Insight Debugger command Enter the executable (shell) command to start Insight, which is usually gdb. Retriever Do not display the warning dialog for multiple matches Select this if you don't want to be warned when the Retriever finds more than one symbol with the name you're searching for. See Retriever for more information about the Retriever. Colors & Fonts tab Source-Navigator assigns a different default color to each component of your source code. To customize these colors or choose different fonts, click the Colors & Fonts tab of the Preferences dialog. Colors & Fonts Tab of the Preferences Dialog From the list of components, choose the item you want to change. The current settings appear in the Font, Foreground, and Background text boxes, and the word "Sample" displays the text with these settings. Changing Fonts Click the "..." button at the end of the Font text entry box. The Choose Font dialog appears: Choose the Family, Name, and Size of font that you would like, as well as Bold or Italics, if you want to use those properties. Click the Apply button to see the effect of your changes and, when you are satisfied, click OK. Your changes take effect the next time you start Source-Navigator. Changing Colors You may want to change the Foreground or Background colors from their default settings if they do not show up well on your laptop or CRT display, or if your code colorization conventions do not match Source-Navigator's default colors. To choose a different color for any component, you must set new RGB (Red-Green-Blue) values. Click the Foreground or Background "..." button. The Choose Color dialog appears. Move the red, green, and blue sliders until the color you want appears in the box at the top of the dialog. Click the Apply button to see how your text or background looks with the new color. If you are satisfied, click OK. Your changes take effect the next time you start Source-Navigator. Contents Previous Next