Man Pages

xcscope(1) - phpMan xcscope(1) - phpMan

Command: man perldoc info search(apropos)  


XCSCOPE.EL(1)                                                    XCSCOPE.EL(1)



NAME
       xcscope.el - xemacs cscope lisp support package

DESCRIPTION
       xcscope is a lisp package for use in integrating cscope functionality into xemacs

INSTALLATION
        Installation steps:


        0. (It is, of course, assumed that cscope is already properly
           installed on the current system.)

        1. Ensure that the location of cscope-indexer is located in your path


        2. Ensure that the location of xcscope.el is in the xemacs module load path


        3. Edit your ~/.emacs file to add the line:

       (require'xcscope)


       5.  If  you  intend  to use xcscope.el often you can optionally edit your ~/.emacs file to add keybindings that
       reduce the number of keystrokes required.  For example, the following will add "C-f#"  keybindings,  which  are
       easier  to  type  than  the  usual  "C-c s" prefixed keybindings.  Note that specifying "global-map" instead of
       "cscope:map" makes the keybindings available in all buffers:
            (define-key global-map [(ctrl f3)]  'cscope-set-initial-directory)
            (define-key global-map [(ctrl f4)]  'cscope-unset-initial-directory)
            (define-key global-map [(ctrl f5)]  'cscope-find-this-symbol)
            (define-key global-map [(ctrl f6)]  'cscope-find-global-definition)
            (define-key global-map [(ctrl f7)]
                 cscope-find-global-definition-no-prompting)
            (define-key global-map [(ctrl f8)]  'cscope-pop-mark)
            (define-key global-map [(ctrl f9)]  'cscope-next-symbol)
            (define-key global-map [(ctrl f10)] 'cscope-next-file)
            (define-key global-map [(ctrl f11)] 'cscope-prev-symbol)
            (define-key global-map [(ctrl f12)] 'cscope-prev-file)
            (define-key global-map [(meta f9)]  'cscope-display-buffer)
            (define-key global-map [(meta f10)] 'cscope-display-buffer-toggle)


        6. Restart (X)Emacs.  That's it.



USING THIS MODULE
   * Basic usage:
        If all of your C/C++/lex/yacc source files are in the same
        directory, you can just start using this module.  If your files are
        spread out over multiple directories, see "Advanced usage", below.


        Just edit a source file, and use the pull-down or pop-up (button 3)
        menus to select one of:

            Find symbol
            Find global definition
            Find called functions
            Find functions calling a function
            Find text string
            Find egrep pattern
            Find a file
            Find files #including a file


       The cscope database will be automatically created in the same directory as  the  source  files  (assuming  that
       you've  never  used cscope before), and a buffer will pop-up displaying the results.  You can then use button 2
       (the middle button) on the mouse to edit the selected file, or you can move the text cursor  over  a  selection
       and press [Enter].


       Hopefully, the interface should be fairly intuitive.


   * Locating the cscope databases:
       This  module  will  first use the variable, 'cscope-database-regexps', to search for a suitable database direc-
       tory.  If a database location cannot be found using this variable then a  search  is  begun  at  the  variable,
       'cscope-initial-directory',  if  set,  or  the  current  directory otherwise.  If the directory is not a cscope
       database directory then the directory's parent, parent's parent, etc.  is  searched  until  a  cscope  database
       directory  is found, or the root directory is reached.  If the root directory is reached, the current directory
       will be used.


       A cscope database directory is one in which EITHER a cscope database file (e.g., "cscope.out") OR a cscope file
       list  (e.g.,  "cscope.files")  exists.   If  only "cscope.files" exists, the corresponding "cscope.out" will be
       automatically created by cscope when a search is  done.   By  default,  the  cscope  database  file  is  called
       "cscope.out",  but  this can be changed (on a global basis) via the variable, 'cscope-database-file'.  There is
       limited support for cscope databases that are named differently  than  that  given  by  'cscope-database-file',
       using the variable, 'cscope-database-regexps'.


       Note that the variable, 'cscope-database-regexps', is generally not needed, as the normal hierarchical database
       search is sufficient for placing and/or locating the cscope databases.  However, there may be  cases  where  it
       makes  sense  to place the cscope databases away from where the source files are kept; in this case, this vari-
       able is used to determine the mapping.  One use for this variable is when you want to share the  database  file
       with other users; in this case, the database may be located in a directory separate from the source files.


       Setting  the  variable,  'cscope-initial-directory',  is useful when a search is to be expanded by specifying a
       cscope database directory that is a parent of the directory that this module would otherwise use.  For example,
       consider a project that contains the following cscope database directories:

            /users/jdoe/sources
            /users/jdoe/sources/proj1
            /users/jdoe/sources/proj2


       If  a  search  is  initiated  from a .c file in /users/jdoe/sources/proj1 then (assuming the variable, 'cscope-
       database-regexps', is not set) /users/jdoe/sources/proj1 will be used as the cscope data base directory.   Only
       matches in files in /users/jdoe/sources/proj1 will be found.  This can be remedied by typing "C-c s a" and then
       "M-del" to remove single path element in order to use a cscope database directory of /users/jdoe/sources.  Nor-
       mal searching can be restored by typing "C-c s A".




   * Keybindings:
       All  keybindings  use  the  "C-c  s"  prefix, but are usable only while editing a source file, or in the cscope
       results buffer:

       C-c s s         Find symbol.

       C-c s d         Find global definition.

       C-c s g         Find global definition (alternate binding).

       C-c s G         Find global definition without prompting.

       C-c s c         Find functions calling a function.

       C-c s C         Find called functions (list functions called
                              from a function).

       C-c s t         Find text string.

       C-c s e         Find egrep pattern.

       C-c s f         Find a file.

       C-c s i         Find files #including a file.


       These pertain to navigation through the search results:


       C-c s b         Display *cscope* buffer.

       C-c s B         Auto display *cscope* buffer toggle.

       C-c s n         Next symbol.

       C-c s N         Next file.

       C-c s p         Previous symbol.

       C-c s P         Previous file.

       C-c s u         Pop mark.


       These pertain to setting and unsetting the variable, 'cscope-initial-directory',  (location  searched  for  the
       cscope database directory):


       C-c s a         Set initial directory.

       C-c s A         Unset initial directory.


       These pertain to cscope database maintenance:

       C-c s L         Create list of files to index.

       C-c s I         Create list and index.

       C-c s E         Edit list of files to index.

       C-c s W          Locate this buffer's cscope directory
                               ( "W" --> "where" ).

       C-c s S         Locate this buffer's cscope directory.
                               (alternate binding: "S" --> "show" ).

       C-c s T         Locate this buffer's cscope directory.
                               (alternate binding: "T" --> "tell" ).

       C-c s D         Dired this buffer's directory.



   * Advanced usage:
       If the source files are spread out over multiple directories, you've got a few choices:


       [  NOTE:  you  will need to have the script, "cscope-indexer", properly installed in order for the following to
       work.  ]


       1. If all of the directories exist below a common directory (without any extraneous, unrelated subdirectories),
       you  can tell this module to place the cscope database into the top-level, common directory.  This assumes that
       you do not have any cscope databases in any of the subdirectories.  If you do, you should delete  them;  other-
       wise, they will take precedence over the top-level database.


       If you do have cscope databases in any subdirectory, the following instructions may not work right.


       It's pretty easy to tell this module to use a top-level, common directory:


       a. Make sure that the menu pick, "Cscope/Index recursively", is checked (the default value).


       b.  Select  the  menu pick, "Cscope/Create list and index", and specify the top-level directory.  This will run
              the script, "cscope-indexer", in the background, so you can do other things if  indexing  takes  a  long
              time.   A list of files to index will be created in "cscope.files", and the cscope database will be cre-
              ated in "cscope.out".


       Once this has been done, you can then use the menu picks (described in "Basic usage", above) to search for sym-
              bols.


       Note,  however,  that,  if you add or delete source files, you'll have to either rebuild the database using the
              above procedure, or edit the file, "cscope.files" to add/delete the names of the source files.  To  edit
              this file, you can use the menu pick, "Cscope/Edit list of files to index".


       2.  If  most  of  the  files  exist below a common directory, but a few are outside, you can use the menu pick,
       "Cscope/Create list of files to index", and specify the top-level  directory.   Make  sure  that  "Cscope/Index
       recursively", is checked before you do so, though.  You can then edit the list of files to index using the menu
       pick, "Cscope/Edit list of files to index".  Just edit the list to include  any  additional  source  files  not
       already listed.


       Once you've created, edited, and saved the list, you can then use the menu picks described under "Basic usage",
       above, to search for symbols.  The first time you search, you will have to wait a while  for  cscope  to  fully
       index  the  source  files,  though.   If you have a lot of source files, you may want to manually run cscope to
       build the database:

            cd top-level-directory    # or wherever
            rm -f cscope.out          # not always necessary
            cscope -b


        3. If the source files are scattered in many different, unrelated
           places, you'll have to manually create cscope.files and put a
           list of all pathnames into it.  Then build the database using:

            cd some-directory         # wherever cscope.files exists
            rm -f cscope.out          # not always necessary
            cscope -b


       Next, read the documentation for the variable, "cscope-database-regexps", and set it appropriately,  such  that
       the above-created cscope database will be referenced when you edit a related source file.


       Once  this  has  been done, you can then use the menu picks described under "Basic usage", above, to search for
       symbols.


   * Interesting configuration variables:
       cscope-truncate-lines

       This is the value of 'truncate-lines' to use in cscope buffers; the default is the current  setting  of  'trun-
       cate-lines'.   This variable exists because it can be easier to read cscope buffers with truncated lines, while
       other buffers do not have truncated lines.


       cscope-use-relative-paths

       If non-nil, use relative paths when creating the list of files to index.  The path is relative to the directory
       in which the cscope database will be created.  If nil, absolute paths will be used.  Absolute paths are good if
       you plan on moving the database to some other directory (if you do so, you'll  probably  also  have  to  modify
       'cscope-database-regexps').   Absolute  paths  may also be good if you share the database file with other users
       (you'll probably want to specify some automounted network path for this).


       cscope-index-recursively

       If non-nil, index files in the current directory and all subdirectories.  If nil, only  files  in  the  current
       directory  are  indexed.  This variable is only used when creating the list of files to index, or when creating
       the list of files and the corresponding cscope database.


       cscope-name-line-width

       The width of the combined "function name:line number" field in the cscope results  buffer.   If  negative,  the
       field is left-justified.


       cscope-do-not-update-database

       If  non-nil,  never check and/or update the cscope database when searching.  Beware of setting this to non-nil,
       as this will disable automatic database creation, updating, and maintenance.


       cscope-display-cscope-buffer

       If non-nil, display the *cscope* buffer after each search (default).  This variable can  be  set  in  order  to
       reduce the number of keystrokes required to navigate through the matches.


       cscope-database-regexps

       List  to  force  directory-to-cscope-database  mappings.   This  is a list of '(REGEXP DBLIST [ DBLIST ... ])',
       where:


       REGEXP is a regular expression matched against the current buffer's current directory.  The current  buffer  is
       typically  some  source  file, and you're probably searching for some symbol in or related to this file.  Basi-
       cally, this regexp is used to relate the current directory to a cscope database.  You need to start REGEXP with
       "^" if you want to match from the beginning of the current directory.


       DBLIST is a list that contains one or more of:

            ( DBDIR )
            ( DBDIR ( OPTIONS ) )
            ( t )
            t


       Here,  DBDIR  is  a directory (or a file) that contains a cscope database.  If DBDIR is a directory, then it is
       expected that the cscope database, if present, has the filename given by the variable,  'cscope-database-file';
       if  DBDIR  is a file, then DBDIR is the path name to a cscope database file (which does not have to be the same
       as that given by 'cscope-database-file').  If only DBDIR is  specified,  then  that  cscope  database  will  be
       searched  without  any  additional cscope command-line options.  If OPTIONS is given, then OPTIONS is a list of
       strings, where each string is a separate cscope command-line option.


        In the case of "( t )", this specifies that the search is to use the
        normal hierarchical database search.  This option is used to
        explicitly search using the hierarchical database search either before
        or after other cscope database directories.


        If "t" is specified (not inside a list), this tells the searching
        mechanism to stop searching if a match has been found (at the point
        where "t" is encountered).  This is useful for those projects that
        consist of many subprojects.  You can specify the most-used
        subprojects first, followed by a "t", and then followed by a master
        cscope database directory that covers all subprojects.  This will
        cause the most-used subprojects to be searched first (hopefully
        quickly), and the search will then stop if a match was found.  If not,
        the search will continue using the master cscope database directory.


        Here, 'cscope-database-regexps' is generally not used, as the normal
        hierarchical database search is sufficient for placing and/or locating
        the cscope databases.  However, there may be cases where it makes
        sense to place the cscope databases away from where the source files
        are kept; in this case, this variable is used to determine the
        mapping.


        This module searches for the cscope databases by first using this
        variable; if a database location cannot be found using this variable,
        then the current directory is searched, then the parent, then the
        parent's parent, until a cscope database directory is found, or the
        root directory is reached.  If the root directory is reached, the
        current directory will be used.


       A cscope database directory is one in which EITHER a cscope database file (e.g., "cscope.out") OR a cscope file
       list  (e.g.,  "cscope.files")  exists.   If  only "cscope.files" exists, the corresponding "cscope.out" will be
       automatically created by cscope when a search is  done.   By  default,  the  cscope  database  file  is  called
       "cscope.out",  but  this can be changed (on a global basis) via the variable, 'cscope-database-file'.  There is
       limited support for cscope databases that are named differently  than  that  given  by  'cscope-database-file',
       using the variable, 'cscope-database-regexps'.


       Here is an example of 'cscope-database-regexps':

            (setq cscope-database-regexps
                  '(
                 ( "^/users/jdoe/sources/proj1"
                   ( t )
                   ( "/users/jdoe/sources/proj2")
                   ( "/users/jdoe/sources/proj3/mycscope.out")
                   ( "/users/jdoe/sources/proj4")
                   t
                   ( "/some/master/directory" ("-d" "-I/usr/local/include") )
                   )
                 ( "^/users/jdoe/sources/gnome/"
                   ( "/master/gnome/database" ("-d") )
                   )
                 ))


       If  the  current buffer's directory matches the regexp, "^/users/jdoe/sources/proj1", then the following search
       will be done:


       1. First, the normal hierarchical database search will be used to
              locate a cscope database.


       2. Next, searches will be done using the cscope database
              directories,      "/users/jdoe/sources/proj2",       "/users/jdoe/sources/proj3/mycscope.out",       and
              "/users/jdoe/sources/proj4".   Note  that,  instead of the file, "cscope.out", the file, "mycscope.out",
              will be used in the directory "/users/jdoe/sources/proj3".


       3. If a match was found, searching will stop.


       4. If a match was not found, searching will be done using
              "/some/master/directory", and the command-line options "-d" and "-I/usr/local/include" will be passed to
              cscope.


       If the current buffer's directory matches the regexp,
              "^/users/jdoe/sources/gnome", then the following search will be done:


       The search will be done only using the directory,
              "/master/gnome/database".  The "-d" option will be passed to cscope.


       If the current buffer's directory does not match any of the above
              regexps, then only the normal hierarchical database search will be done.



   * Other notes:
       1.  The  script,  "cscope-indexer",  uses a sed command to determine what is and is not a C/C++/lex/yacc source
       file.  It's idea of a source file may not correspond to yours.


       2. This module is called, "xcscope", because someone else has already  written  a  "cscope.el"  (although  it's
       quite old).


KNOWN BUGS:
       1. Cannot handle whitespace in directory or file names.


       2. By default, colored faces are used to display results.  If you happen to use a black background, part of the
       results may be invisible (because the foreground color may be black, too).  There are at  least  two  solutions
       for this:


       2a. Turn off colored faces, by setting 'cscope-use-face' to 'nil', eg:

       (setq cscope-use-face nil)


        2b. Explicitly set colors for the faces used by cscope.  The faces are

                   cscope-file-face
                   cscope-function-face
                   cscope-line-number-face
                   cscope-line-face
                   cscope-mouse-face


       The face most likely to cause problems (e.g., black-on-black
              color) is 'cscope-line-face'.


       3.  The support for cscope databases different from that specified by 'cscope-database-file' is quirky.  If the
       file does not exist, it will not be auto-created (unlike files names by 'cscope-database-file').  You can manu-
       ally  force the file to be created by using touch(1) to create a zero-length file; the database will be created
       the next time a search is done.



Darryl Okahata                    April 2000                     XCSCOPE.EL(1)