FREESCOPE(1)

NAME
freescope - source code browser

SYNOPSIS
freescope [-bdfhlVZ] [-f database]

DESCRIPTION
freescope is a source code browser similar to the "cscope" program. It allows the user to interactively query a symbol database. The database is built and updated by examining source files specified in the "freescope.files" file. If "freescope.files" is not found, freescope tries to open the file "cscope.files" and treats that file as if it was "freescope.files". freescope also parses recursively all header files that are directly or indirectly included by the source files listed in freescope.files.

Upon first invocation of freescope , a database is built and saved under the file "freescope.out". On subsequent execution, freescope updates its database only for the files that have been modified since last invocation of the browser.

Currently, freescope can parse C files. It is intended that in the future, the program parsing capabilities will be extended to other languages such as C++, Java, Pascal, etc.

OPTIONS
Here is a list of options currently supported by freescope:

-b  Build the database and exit immediately.

-d  Do not update the database on startup.

-f <database>
    Open "database" file instead of freescope.out

-h  Display a small help message about usage.

-l  Start freescope in CLI mode instead of curses. See below.

-V  Display the program's version and exit immediately.

-Z  Dump database to the standard output. Debugging purpose.

USAGE
Upon update completion, the user can enter a query under one of the following categories:

- Symbol:               Find any occurence for this symbol
- Global definition:    Find global definitions for this symbol
- Functions called by:  Find functions calling this function
- Functions calling:    Find calls to this function
- Text:                 Find occurences of this text string
- Change text:          Substitute given text with a new string
- Regular exp:          Find occurences of this regular expression
- File:                 Find the files matching this regular expression
- File including:       Find places where this file is included
The user can change the type of query using the <UP> or <DOWN> arrow, or by pressing the <TAB> key.
The program provides symbol completion during input of a symbol. To use this feature, the user has to press <CTRL>-N to get the next possible completion and <CTRL>-P to get the previous displayed completion.

The user can navigate across results by using the following keys:
j   Highlight next result on the current page.
k   Highlight previous result on the current page.
l   Show next result page if available
h   Show previous result page if available
<RETURN> / <SPACE>
    Open editor on the selected result
Note that the arrow keys can also be used.

The user switches between browse and query mode by pressing the <CTRL-W> key. <TAB> key can also be used while in browse mode.

A help panel can be displayed at any time by pressing the ? key.

Other commands are:
<CTRL-D> Exit freescope.
<CTRL-B> Previous query
<CTRL-F> Next query
<CTRL-R> Update database

CHANGING TEXT
When selecting the "Change text" query, the user is asked to select the matches that need to be modified. Navigating the matches is as described above.
Selection is made by pressing the s key which results in freescope highlighting the beginning of the result line. Deselecting a match is done by pressing again the s key.
All matches can be selected using the <CTRL-A> command.
The user confirm his selection by typing <CTRL-D>
It is possible to cancel the changing operation by typing <CTRL-C>

COMMAND LINE INTERFACE
Freescope can be started as a CLI by specifying the -l option. The implemented commands are similar to the cscope CLI commands.
freescope will prompt the ">>" string when ready to accept input commands.
Input commands must start with the field number associated with the type of query. This field number is counting from 0. The search pattern must immediately follow. For example:
>> 3printf
will find all places where the "printf" function is called.
Each search result is displayed with the following format: filename, scope name, line number and line text. For example:
main.c main 124 printf("hello world);
The r command is used for rebuilding the database.
The q command stops freescope.

INTEGRATING VIM AND FREESCOPE
Since version 0.2.0, freescope can be integrated with the vim text editor.
To do so, make sure that vim has been compiled with cscope support. Then, add the following lines in your .vimrc configuration file:
set csprg=freescope
set csto=0
set cst
set nocsverb
set csverb
cs add whatever_directory/freescope.out
You can customize your .vimrc file to your own taste of course.
Have a look at http://freescope.sourceforge.net for useful vim macros for freescope and cscope.

CONFIGURATION FILE
freescope supports reading a configuration file since release 0.3.0. The configuration file is assumed to be the content of the environment variable FREESCOPERC if set. Otherwise, the configuration file is assumed to be called ".freescoperc" and located under the path pointed by the "HOME" environment variable. If the "HOME" environment variable is not set, the file ".freescoperc" is assumed to be located under the root directory.
The configuration file is constituted of lines made of PARAMETER-VALUE pairs and results in certain parameters being set in the program. Empty lines and lines starting with a "#" symbol are ignored. Note that all parameter names must be uppercase.
Special keys (Such as function keys, escape, control keys, etc.) must be entered as one character in the configuration file. For example, this can be done with vim using the CTRL-V command. PARAMETER LIST
============== DB_FILE
Cross-reference file to be generated (def "freescope.out"). INPUT_FILE.
Input file containing all files to be parsed (def: "freescope.files"). UPDATE_ON_STARTUP
Specify if the database should be updated upon startup (def: "yes"). KEY_NEXT_SELECTION
Key mapping for selecting next match (def: "k"). KEY_PREV_SELECTION
Key mapping for selecting previous match (def: "j"). KEY_NEXT_PAGE
Key mapping for going to next page of results (def: "l"). KEY_PREV_PAGE
Key mapping for going to previous page of results (def: "h"). KEY_NEXT_QUERY
Key mapping for going to next query (def: "TAB"). KEY_PREV_QUERY
Key mapping for going to previous query (def: "h"). KEY_SWITCH_MODE
Key mapping for switching between QUERY and NAVIGATE mode (def: "CTRL-W"). KEY_NEXT_COMPLETION
Key mapping for getting next symbol completion (def: "CTRL-N"). KEY_PREV_COMPLETION
Key mapping for getting previous symbol completion (def: "CTRL-P"). KEY_REBUILD_DB
Key mapping for updating database (def: "CTRL-R"). KEY_HISTORY_BACKWARD
Key mapping for navigating backwards into the query history (def: "CTRL-B"). KEY_HISTORY_FORWARD Key mapping for navigating forwards into the query history (def: "CTRL-F").

FREESCOPE WITH MICROSOFT WINDOWS
Freescope has been ported to Microsoft Windows since release 0.2.1.
I really advise whoever wants to use freescope under that platform to install the Cygwin environment (http://www.cygwin.com). Having a Bash shell is *much* more conveninent than the COMMAND.COM interpreter from Microsoft... Also, rxvt is part of the Cygwin contribution packages and provides a terminal superior to the conventionnal DOS window.
Note about vim and freescope under Windows: For some reason, vim crashes when I try to start it with freescope from a DOS window (This problem doesn't occur with Emacs). For this reason, I would advise again to use rxvt as this problem doesn't occur with this terminal.

ENVIRONMENT VARIABLES
VIEWER
Preferred editor. Default is "vi"
EDITOR
Preferred editor if the VIEWER environment variable is not set. Default is "vi"

SEE ALSO
Have a look at the cscope application.

WEB SITE
http://freescope.sourceforge.net
http://freescope.sf.net