consult-cscope

Overview and Usage

This package provides cscope support for the consult interface for Emacs. consult-cscope runs asynchronously similar to consult-grep and provides the following interactive functions corresponding to each of the search types cscope can perform:

consult-cscope-symbol Search for all references to this symbol.
consult-cscope-definition Search for the global definition of this symbol.
consult-cscope-called-by Search for all functions called by this function.
consult-cscope-calling Search for all functions calling this function.
consult-cscope-text Search for this text string.
consult-cscope-egrep Search for this egrep pattern.
consult-cscope-file Search for this file.
consult-cscope-including Search for any files including this file.
consult-cscope-assignment Search for any assignments to this symbol. (only in cscope 15.8+)

Since consult-cscope uses consult’s asynchronous search interface, results can be narrowed using various splitting styles.

Some examples using the perl splitting style:

#function: Search for function symbol.
#function#filter: Search for function symbol and only show results also containing filter.
#function -- -C: Pass -C flag to cscope to make search case-insensitive.

Configuration

Basic configuration is done using a few variables:

consult-cscope-program: Path or filename of cscope executable. Defaults to “cscope”, which should be enough if cscope is available in your PATH.
consult-cscope-database-file: Path or filename of cscope database file. Can be an absolute or relative path. Defaults to “cscope.out” which will cause consult-cscope to look in several locations as detailed in the Database file configuration section.
consult-cscope-args: Extra command line arguments for cscope. Defaults to “-d”, which causes cscope to skip building the database file. Don’t add “-f” or “-L” here as these are used automatically.
consult-cscope-use-initial: When set to nil (default), consult-cscope searches don’t provide initial input but add it to the “future history”. Using a prefix argument before the search adds initial input. When set to non-nil, this behavior is reversed and initial input is automatically added unless a prefix argument is provided.

Database File Search Order

consult-cscope uses the consult-cscope-database-file variable to determine the location of the cscope database file in the following search order:

If consult-cscope-database-file is an absolute path, use the path as-is.
If consult-cscope-database-file is a relative path (e.g. the default “cscope.out”), search the current directory.
Search the directory returned by the projectile-project-root function.

consult-cscope assumes a cscope database file has already been built (for example with the cscope -b terminal command).

Per-Directory Local Configuration

Per-directory local variables can be used with consult-cscope to allow for per-project configuration of consult-cscope-program and consult-cscope-database-file. This can be especially useful when using shared, pre-built cscope database files.

For example, if you have a project that has a cscope database file in ~/project/cscope/cscope.out, you would add a .dir-locals.el file in ~/project/ with the following configuration:

((nil . ((consult-cscope-database-file "~/project/cscope/cscope.out"))))

Then, any files being edited in or in a subdirectory of ~/project/ will use this value for cscope-database-file.

Installation

Manual

Add consult-cscope.el to your load-path and use require or use-package.

Doom Emacs

consult-cscope can be added to Doom Emacs by adding the following to ~/.doom.d/packages.el:

(package! consult-cscope :recipe (:host github :repo "blorbx/consult-cscope"))

Further customization can be added to ~/.doom.d/config.el. An example configuration:

(use-package! consult-cscope
  :defer t
  :commands (consult-cscope-symbol
             consult-cscope-definition
             consult-cscope-called-by
             consult-cscope-calling
             consult-cscope-text
             consult-cscope-egrep
             consult-cscope-file
             consult-cscope-including
             consult-cscope-assignment))

(map! :localleader
      :map (c-mode-map c++-mode-map)
      (:prefix ("g" . "goto")
       :desc "Find this symbol" "r" #'consult-cscope-symbol
       :desc "Find this global definition" "d" #'consult-cscope-definition
       :desc "Find functions called by this function" "c" #'consult-cscope-called-by
       :desc "Find functions calling this function" "C" #'consult-cscope-calling
       :desc "Find this text string" "x" #'consult-cscope-text
       :desc "Find this egrep pattern" "e" #'consult-cscope-egrep
       :desc "Find this file" "f" #'consult-cscope-file
       :desc "Find this files including this file" "F" #'consult-cscope-including
       :desc "Find assignments to this symbol" "R" #'consult-cscope-assignment))

MELPA

This package has not yet been added to MELPA.