.PU .TH FREESCOPE "1" "July 2001" "Olivier Deme" .SH NAME freescope - source code browser .SH SYNOPSIS .ll +8 .B freescope .RB [ "-bdfhlVZ" ] .RB [ "-f database" ] .SH DESCRIPTION .I 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". .I freescope also parses recursively all header files that are directly or indirectly included by the source files listed in freescope.files. .PP Upon first invocation of .I freescope , a database is built and saved under the file "freescope.out". On subsequent execution, .I freescope updates its database only for the files that have been modified since last invocation of the browser. .PP Currently, .I 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. .SH OPTIONS Here is a list of options currently supported by .I freescope: .TP .B -b Build the database and exit immediately. .TP .B -d Do not update the database on startup. .TP .B -f Open "database" file instead of freescope.out .TP .B -h Display a small help message about usage. .TP .B -l Start freescope in CLI mode instead of curses. See below. .TP .B -V Display the program's version and exit immediately. .TP .B -Z Dump database to the standard output. Debugging purpose. .SH USAGE Upon update completion, the user can enter a query under one of the following categories: .TP - Symbol: Find any occurence for this symbol .PD 0 .TP - Global definition: Find global definitions for this symbol .TP - Functions called by: Find functions calling this function .TP - Functions calling: Find calls to this function .TP - Text: Find occurences of this text string .TP - Change text: Substitute given text with a new string .TP - Regular exp: Find occurences of this regular expression .TP - File: Find the files matching this regular expression .TP - File including: Find places where this file is included .PP The user can change the type of query using the .B or .B arrow, or by pressing the .B key. .PP The program provides symbol completion during input of a symbol. To use this feature, the user has to press .B -N to get the next possible completion and .B -P to get the previous displayed completion. .PD 1 .PP The user can navigate across results by using the following keys: .PD 0 .TP .B j Highlight next result on the current page. .TP .B k Highlight previous result on the current page. .TP .B l Show next result page if available .TP .B h Show previous result page if available .TP .B / Open editor on the selected result .PP Note that the arrow keys can also be used. .PD 1 .PP The user switches between browse and query mode by pressing the .B key. .B key can also be used while in browse mode. .PP A help panel can be displayed at any time by pressing the .B ? key. .PP Other commands are: .PD 0 .PP .B Exit freescope. .PP .B Previous query .PP .B Next query .PP .B Update database .SH 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. .PP Selection is made by pressing the .B s key which results in freescope highlighting the beginning of the result line. Deselecting a match is done by pressing again the .B s key. .PP All matches can be selected using the .B command. .PP The user confirm his selection by typing .B .PP It is possible to cancel the changing operation by typing .B .SH COMMAND LINE INTERFACE Freescope can be started as a CLI by specifying the .B -l option. The implemented commands are similar to the .I cscope CLI commands. .PP freescope will prompt the ">>" string when ready to accept input commands. .PP 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: .PP >> 3printf .PP will find all places where the "printf" function is called. .PP Each search result is displayed with the following format: filename, scope name, line number and line text. For example: .PP main.c main 124 printf("hello world\n"); .PP The .B r command is used for rebuilding the database. .PP The .B q command stops freescope. .SH INTEGRATING VIM AND FREESCOPE Since version 0.2.0, freescope can be integrated with the .I vim text editor. .PP To do so, make sure that .I vim has been compiled with .I cscope support. Then, add the following lines in your .I .vimrc configuration file: .PP set csprg=freescope .PP set csto=0 .PP set cst .PP set nocsverb .PP set csverb .PP cs add whatever_directory/freescope.out .PP You can customize your .I .vimrc file to your own taste of course. .PP Have a look at http://freescope.sourceforge.net for useful .I vim macros for freescope and .I cscope. .SH 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 .B 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. .PP 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. .PP 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 .I vim using the .B CTRL-V command. .T PARAMETER LIST .PP ============== .B DB_FILE .PP Cross-reference file to be generated (def "freescope.out"). .B INPUT_FILE. .PP Input file containing all files to be parsed (def: "freescope.files"). .B UPDATE_ON_STARTUP .PP Specify if the database should be updated upon startup (def: "yes"). .B KEY_NEXT_SELECTION .PP Key mapping for selecting next match (def: "k"). .B KEY_PREV_SELECTION .PP Key mapping for selecting previous match (def: "j"). .B KEY_NEXT_PAGE .PP Key mapping for going to next page of results (def: "l"). .B KEY_PREV_PAGE .PP Key mapping for going to previous page of results (def: "h"). .B KEY_NEXT_QUERY .PP Key mapping for going to next query (def: "TAB"). .B KEY_PREV_QUERY .PP Key mapping for going to previous query (def: "h"). .B KEY_SWITCH_MODE .PP Key mapping for switching between QUERY and NAVIGATE mode (def: "CTRL-W"). .B KEY_NEXT_COMPLETION .PP Key mapping for getting next symbol completion (def: "CTRL-N"). .B KEY_PREV_COMPLETION .PP Key mapping for getting previous symbol completion (def: "CTRL-P"). .B KEY_REBUILD_DB .PP Key mapping for updating database (def: "CTRL-R"). .B KEY_HISTORY_BACKWARD .PP Key mapping for navigating backwards into the query history (def: "CTRL-B"). .B KEY_HISTORY_FORWARD Key mapping for navigating forwards into the query history (def: "CTRL-F"). .SH FREESCOPE WITH MICROSOFT WINDOWS Freescope has been ported to Microsoft Windows since release 0.2.1. .PP I really advise whoever wants to use freescope under that platform to install the .I Cygwin environment (http://www.cygwin.com). Having a Bash shell is *much* more conveninent than the COMMAND.COM interpreter from Microsoft... Also, .I rxvt is part of the .I Cygwin contribution packages and provides a terminal superior to the conventionnal DOS window. .PP .B Note about .I vim and freescope under Windows: For some reason, .I 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. .SH ENVIRONMENT VARIABLES .B VIEWER .PP Preferred editor. Default is "vi" .PP .B EDITOR .PP Preferred editor if the .B VIEWER environment variable is not set. Default is "vi" .SH SEE ALSO Have a look at the .B cscope application. .SH WEB SITE http://freescope.sourceforge.net .PP http://freescope.sf.net