1. Working with Environments

In order to browse code from a set of libraries or an entire system, an OO-Browser Environment must first be created. An OO-Browser Environment defines the set of entities that are browsable within a session of the browser. The first step in creating an Environment is to create an Environment specification which tells the browser the name of the Environment, where to save its browsing data, what programming language the Environment should support, and what directories to scan for source code to browse. (See section 1.1 Creating Environments, for more information.)

Once an Environment has been specified, it can be built, a process which scans the set of directory trees given in the Environment specification and saves data about classes, methods, attributes, formal protocols (interfaces) and relationships among these entities for later browsing.

Whenever the OO-Browser is in use, an Environment is selected. The phrase, the Environment, refers to the current OO-Browser Environment. Many browser commands depend upon information in the Environment.

The set of source files included in an Environment is specified by two lists of top-level (root) directories whose subdirectories are automatically scanned by the OO-Browser. The first list of directories is called the system-specific directory list; it defines the locations of unreleased code being developed, often for a particular system. The second list is called the reusable library directory list; it defines the locations of stable, reusable classes that have been released for general use. All class names within a single Environment must be unique to ensure proper operation of the browser (Duplicate classes will be flagged by the browser for later removal. Use {M-e} (br-env-stats) in a browser listing window to help find duplicate classes.)

The OO-Browser lets you name, create, update and save Environments. Once an Environment has been created, it may be loaded at any time. The browser will then use this Environment for all of its operations until another one is loaded.

Within each editor session, the browser caches a separate Environment for each programming language on which it is used. Thus, if you switch from Eiffel to C++ browsing and then back to Eiffel browsing, the Eiffel environment will not need to be reloaded; it will appear immediately and the frame will appear as if the Eiffel OO-Browser were invoked for the first time.

Environment files are automatically saved by the OO-Browser so that you need never become familiar with their format. You are responsible for requesting the use of a particular Environment whenever desired. See section Invoking the OO-Browser, for information on how to specify a different Environment file for use.

1.1 Creating Environments

Environments may be specified, built and/or loaded at any time all with one command, whether or not the browser user interface is on screen. Use the {C-c C-o} (oo-browser) command to select a language and Environment to create or to load by name. (Some programming modes may override that key binding, so a menu item or `M-x oo-browser RET' are the surefire ways to invoke this command.)

If you have browsed a prior Environment during your current editor session, you will be asked whether or not to reload that Environment. If you type `n' for no or if no prior Environment has been loaded, you will be prompted for an Environment name to load; full completion is available.

If instead of typing an Environment name, you simply press Return, you will be prompted for the pathname of an Environment file to load. This lets you specify Environments created prior to version 4 of the OO-Browser, which did not have names. The default is to load the Environment file in the current directory whose name is given by the br-env-default-file variable, which is normally set to `OOBR'.

If you give an Environment name or file which does not exist, you will be prompted to create a specification for this new Environment. The recommended default name for Environment files is, `OOBR'. It is best to save each Environment within the top-level directory of the first system-specific directory of the Environment, i.e. the root directory of a system's code.

Every Environment must be specified before it can be built or used. Here are the Environment specification components for which you will be prompted:

Top-level system-specific code directories

A list of root directories below which system source code may be found. Each directory is prompted for individually and argument completion is available.

Top-level reusable library code directories

A list of root directories below which library source code may be found. Each directory is prompted for individually and argument completion is available.

Environment specifications are useful when you want to describe a number of Environments to the OO-Browser yet also want to defer their construction until later. Large environments then can be built overnight. When in an OO-Browser listing window, multiple Environment specifications may be created in quick succession with the {C-c C-c} (br-env-browse) command, which prompts for all necessary information to create an Environment specification; simply give it a non-existing Environment name and answer no when prompted to build the Environment to defer building for later. The OO-Browser will automatically prompt you to build an Environment specification whenever you try to load it for browsing.

1.2 Building Environments

An Environment specification tells the OO-Browser what to include in the Environment, but the Environment must be built by scanning the source directories before it can be used. When a new Environment is to be built or when a large number of changes have been made to classes in the current Environment, the following commands are useful:

{C-c C-e} (br-env-rebuild) within an OO-Browser

listing window scans all Environment source code directories. This prompts for whether or not to use a background process to build the Environment (if a `make' program is available), so that other tasks may be performed while the build is active. With a prefix argument under InfoDock or XEmacs, {C-u C-c C-e}, it runs the build in the background and produces a stack backtrace if an error occurs during the build;

{L} (br-lib-rebuild)

scans only the reusable library directories of the Environment;

{S} (br-sys-rebuild)

scans only the system-specific directories of the Environment.

Whenever class inheritance relations or the set of attributes or methods for a class changes, the Environment must be rebuilt, but this is generally a fast process.

The OO-Browser lets you build large Environments in the background of your interactive session (if a `make' program is available), allowing other work to proceed without waiting on a build. When a build is complete, the OO-Browser will prompt you and give you a choice of whether or not to browse the built Environment immediately.

Alternatively, any number of very large Environments may be built overnight by invoking Emacs in batch mode from a shell script. To do this, you must first create an Environment specification so that the browser knows what to build. See section 1.1 Creating Environments. Then use a shell command line of the form below (substitute your local OO-Browser installation directory for Br-Dir):

cd Br-Dir; emacs -batch -l ./br-start.elc Env-Spec-File-1 \
   ... Env-Spec-File-N -f br-env-batch-build > Log-File

cd oo-browser; emacs -batch -l ./br-start.elc ~/OOBR \
   -f br-env-batch-build > log-file

Redirection of the standard output stream to a log file for later examination helps ensure that either the Environment build is successful or an error is logged.

1.3 Saving Environments

The OO-Browser automatically builds and saves Environments in most cases. Occasionally you may find a need to force the Environment to be saved to a file, as in the case when you want to save an Environment under a different file name.

Use {C-c C-s}, the (br-env-save) command, to force a save of the current Environment. The command will prompt for a file to save to, with the present Environment file name as the default.

1.4 Managing Environment Names

The OO-Browser offers a set of menu and keyboard-based commands for managing user-specific names associated with Environment files. The menu commands are found on the Environment menu within browser listing buffers. See section B. Menus. The related keyboard commands are for use within listing buffers.

Each time you create an Environment, you give it a memorable name which is stored with the associated Environment file name, in a file given by the variable, br-names-file. This variable is set to `~/.oo-browser' on UNIX-like OSes and `c:/_oo-browser' on Microsoft operating systems. This Environment names file is loaded by the OO-Browser at startup so that it can offer completion to assist you when entering Environment names. The Environment names file is automatically saved whenever necessary by the browser.

Once an Environment has been loaded, your full list of Environment names can be displayed with the {M-l} (br-names-display) command. This shows each name together with its Environment file name.

If you want to browse an Environment created by another user or want to add additional names to an Environment, when in the browser, use the {M-a} (br-name-add) command. This will prompt for a name and an existing Environment file with which to associate the name.

Use the {M-n} (br-name-change) command to rename an Environment. The command, {M-m} (br-name-remove), will delete an existing name. It removes the name only, not the Environment itself. The {M-r} (br-name-replace) command will change the Environment file associated with a particular name.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.