Справочник по Vim: Использование cscope с Vim

СПРАВОЧНИК ПО VIM - Энди Кан

Этот документ объясняет, как пользоваться интерфейсом Vim для cscope.

Cscope это программа, похожая на ctags, но позволяющая делать гораздо больше. Можете относиться к ней как к ctags "на стероидах". В Vim прыжок к ответу на запрос к cscope ничем не отличается от прыжку к любой другой метке. Такой прыжок сохраняется в стеке меток, так что при условии использования правильных привязок клавиш можно перемещаться между функциями аналогично использованию обычных |меток|.

1. Введение в cscope
2. Команды, относящиеся к cscope
3. Опции cscope
4. Использование cscope в Vim
5. Ограничения
6. Советы по использованию
7. Доступность и информация о cscope

Эта информация в текущий момент имеет отношение только к Unix и Win32.
Vi не имеет описываемых в этом документе команд.

1. Введение в cscope

Нижеследующий текст взят из страницы справочника man для cscope:

  Cscope это интерактивное экранное средство, которое помогает:

• Изучить, как работает программа на C без ручного поиска в исходных текстах.
• Искать раздел в коде для исправления ошибки без необходимости изучения структуры всей программы.
• Выяснять последствия предполагаемых изменение, таких как например добавление значения к переменной типа enum.
• Убедиться, что необходимые изменения внесены во все исходные файлы, например при добавлении аргумента к существующей функции.
• Изменять имя глобальной переменной во всех файлах с исходными текстами.
• Изменять константы в символах препроцессора в выбранных строках кода.

  Эта программа задумана для получения ответов на вопросы:

• Где используется данный символ?
• Где он определён?
• Откуда данная переменная получает своё значение?
• Как определён данный глобальный символ?
• Где в исходных текстах находится данная функция?
• Какие функции вызывают данную функцию?
• Какие функции вызываются данной функцией?
• Откуда берётся сообщение вроде "out of space" в этой программе?
• Где находится данный файл с исходным текстом в структуре файловой системы?
• Какие файлы включают данный заголовочный файл?

Cscope отвечает на эти вопросы, пользуясь собственной базой данных по символам, которая создаётся при первом запуске cscope с данным исходным текстом. При последующих вызовах, база данных обновляется только в том случае, если файлы исходных текстов были изменены, или изменён список файлов исходных текстов. При изменении базы данных, данные для неизменённых файлов копируются их старой базы данных, что позволяет перестраивать базу данных намного быстрее, чем при первом запуске.

При обычном запуске cscope перед вами появляется полноэкранное меню для выбора того или иного запроса, соответствующего указанным выше вопросам. К сожалению, после того как ответ на запрос получен и cscope передаёт управление текстовому редактору для редактирования содержащего соответствие с результатами запроса исходного текста, дальнейшее перемещение от запроса к запросу при помощи обычных команд vi CTRL-] или :tag, не работает.

Чтобы исправить положение был создан интерфейс к cscope для Vim, который вызывает cscope в режиме командной строки и затем распознаёт вывод программы в ответ на тот или иной запрос. В результате, запросы к программе cscope выглядят как обычные метки, по которым можно перемещаться с помощью команд редактора (CTRL-] или :tag), и затем возвращаться на исходную позицию с помощью команды CTRL-T. (Обратите внимание, что прежде всего следует выполнить переназначение привязок для этих команд, или настроить соответствующие опции, иначе интерфейс к cscope работать не будет. В нижеследующих разделах описано как можно использовать интерфейс и как он работает.)

2. Команды, относящиеся к cscope

Все команды cscope доступны через дополнительные опции главной команды cscope  ":cscope". Самое короткое сокращение для этой команды -- ":cs". Команда  ":scscope" выполняет те же действия, но в новом разделённом окне (сокращённое имя: "scs").

Доступные подкоманды:
add   : Добавить новую базу данных.

ИСПОЛЬЗОВАНИЕ :cs add {file|dir} [pre-path] [flags]

[pre-path] путь для ключа -P команды cscope.

[flags] любые дополнительные ключи для команды cscope.

ПРИМЕРЫ

:cscope add /usr/local/cdb/cscope.out
:cscope add /projects/vim/cscope.out /usr/local/vim
:cscope add cscope.out /usr/local/vim -C

find  : Запрос к cscope.  Доступны все запросы cscope, кроме запроса #5 ("Изменение шаблона grep").

ИСПОЛЬЗОВАНИЕ :cs find {тип-запроса} {имя}

{тип-запроса} соответствует номерам запросов, доступных из
командной строки cscope или командам nvi:

0 или s: Найти данный символ C
1 или g: Найти данное определение
2 или d: Найти функции, вызываемые данной функцией
3 или c: Найти функции, вызывающие данную функцию
4 или t: Найти указанную текстовую строку
6 или e: Найти указанный шаблон egrep
7 или f: Найти данный файл
8 или i: Найти файлы, включающие данный файл при помощи #include

ПРИМЕРЫ

:cscope find c vim_free
:cscope find 3 vim_free

Эти два примера выполняют один и тот же запрос.

:cscope find 0 DEFAULT_TERM

Выполнение этого примера на исходном коде Vim 5.1 выдаёт следующий результат:

Метки cscope: DEFAULT_TERM

Введите номер для выбора (или <CR> чтобы отказаться):

В выводе содержится несколько элементов информации:

1. Номер метки (в данном примере 15 меток).
2. Номер строки с меткой.
3. Имя файла, где находится метка.
4. Контекст метки (например, global или имя функции).
5. Строка файла.

help: Показать краткую справку.

ИСПОЛЬЗОВАНИЕ :cs help

kill  : Убить соединение с cscope (или убить все соединения cscope).

ИСПОЛЬЗОВАНИЕ :cs kill {номер|часть_имени}

Чтобы убить соединение с cscope, необходимо указать номер соединения или часть имени соединения. Часть имени это любой фрагмент пути к базе данных cscope. Пользуйтесь убийством соединений с использованием частичного имени с осторожностью!

Если указано соединение -1, то будут убиты ВСЕ соединения с cscope.

reset : Повторная инициализация всех подсоединений к cscope.

ИСПОЛЬЗОВАНИЕ :cs reset

show  : Показать соединения с cscope.

ИСПОЛЬЗОВАНИЕ :cs show

Если вы используете cscope совместно с ctags, то |:cstag| позволяет выполнять перед прыжком поиск по тому или иному списку. Например, вы можете начать поиск с баз(ы) данных cscope, и если метка не будет найдена, то поискать также и в файлах меток tags. Порядок, в котором происходит поиск, определяется значением |csto|. Подробнее смотрите в |cscope-опции|.

Команда |:cstag| выполняет поиск аналогично команде ":cs find g" для данного имени, если поиск ведётся в базах данных cscope.

При поиске в файлах меток tags, |:cstag| выполняет действия, аналогичные выполнению команды |:tjump| для данного имени.

3. Опции cscope

Для установки опций cscope используйте команду |:set|. Лучше всего выполнять установку опций из файлов сценария запуска, например .vimrc. Некоторые переменные, относящиеся к cscope допустимо использовать только в |.vimrc|. Их установка после запуска Vim не будет иметь никакого эффекта!

Опция 'cscopeprg' указывает на команды, которая выполняется для запуска cscope.
Значение по умолчанию: "cscope".
Пример:

:set csprg=/usr/local/bin/cscope

                            ** *csqf* *E469*
Доступно только в том случае, если Vim скомпилирован с особенностью |+quickfix|.

Опция 'cscopequickfix' определяет порядок использования окна быстрого исправления для демонстрации результатов работы cscope. Значением опции является список разделённых запятой величин. Каждая величина состоит из команды поиска |cscope-find| (s, g, d, c, t, e, f или i) и специального флага (+, - или 0).

'+' указывает на то, что результат должен быть добавлен к текущему содержанию окна быстрого исправления, '-' предполагает очистку предыдущих результатов, '0' или отсутствие команды -- запрет на использование окна быстрого исправления. Поиск осуществляется от начала значения до первого появления команды. Значением опции по умолчанию является "" (т.е. не использовать окно быстрого исправления вообще). Полезным может оказаться такое значение: "s-,c-,d-,i-,t-,e-".

При включённой опции 'cscopetag', команды ":tag" и CTRL-], а также "vim -t" будут всегда использовать |:cstag| вместо :tag. При этом всегда будет происходить поиск в базах данных cscope, в дополнение к поиску по файлам меток.

Значение по умолчанию: выключено.

Примеры:

:set cst
:set nocst

Значение 'csto' определяет порядок поиска для |:cstag|. Если опция 'csto' установлена равной нулю, то сначала происходит поиск в базах данных cscope, затем поиск может быть продолжен в файлах меток tags, если cscope ничего не найдёт. При значении опции 'csto' равном единице, поиск в файлах меток tags осуществляется перед поиском в базах данных cscope.

Значение по умолчанию: 0.

Примеры:

:set csto=0
:set csto=1

При выключенной опции 'cscopeverbose', команда добавления базы данных cscope не будет выводить диагностическую информацию об успешном или неудачном подсоединении. Лучше всего выключать эту опцию в |.vimrc| перед добавлением баз данных cscope из .vimrc, и затем снова включать эту опцию. В этом случае, при добавлении дополнительных баз данных из редактора Vim будет выдавать некоторую дополнительную информацию о процессе подключения базы.

Значение по умолчанию: выключено.

Примеры:

:set csverb
:set nocsverb

Значение опции 'cspc' определяет количество компонентов пути к файлу, которое будет отображаться при выводе. При значении опции равном нулю будет отображаться полный путь к файлу. Значение 1 позволяет показывать только само имя файла, без указания пути. Другие значения позволяют отображать соответствующее количество компонентов.

Значение по умолчанию: 0.

Примеры:

:set cspc=3

будет показывать последние 3 компонента пути файла, включая само имя файла.

4. Использование cscope в Vim

Прежде всего вам потребуется создать базу данных cscope для ваших исходных текстов. Самый простой способ сделать это -- запустить программу "cscope -b". За дополнительной информацией обращайтесь к странице справочника man для cscope.

Если у вас есть база данных cscope, то её необходимо добавить в редакторе Vim. Эта операция устанавливает "соединение" cscope и позволяет использовать это соединение из редактора. Операцию по добавлению базы данных можно выполнять из сценария запуска .vimrc или вручную после запуска Vim. Например, для добавления базы данных "cscope.out", введите команду

:cs add cscope.out

Результат выполнения этой команды можно проверить командой ":cs show". Вывод этой команды примерно такой:

# pid     имя базы данных         дополнительный путь
0 28806   cscope.out              <нет>

Замечание: Из-за ограничений Microsoft RTL, в версии Win32 вместо реального идентификатора процесса pid показывается 0.

После установления соединения с базой данных cscope вы можете осуществлять запросы к cscope и получать результаты выполнения запросов. Запросы к cscope производятся командой ":cs find". Например:

:cs find g ALIGN_SIZE

Поскольку соответствующие команды требуют слишком больших усилий при наборе, то можно настроить привязки для клавиатуры. Подробнее об этом смотрите в |cscope-советы|.

Если в результате запроса будет найдено только одно соответствие, то Vim автоматически откроет нужный файл и установит курсор в требуемой позиции. Если соответствий несколько, то вам будет представлен их список для выбора. После перехода к новой метке можно пользоваться CTRL-T для возврата к исходной позиции.

5. Ограничения

Поддержка cscope для Vim доступна только на системах, поддерживающих системные вызовы fork(), pipe(), execl() и waitpid(). На практике это означает, что поддержка в основном ограничена системами Unix.

Кроме того, cscope может работать на платформе Win32. Для получения дополнительной информации и программного обеспечения cscope для Win32, обращайтесь по адресу:

• https://iamphet.nm.ru/cscope/index.html

Кроме того, имеется ряд дополнительных ограничений:

1. Максимальное количество соединений с cscope ограничено 8. Вам на самом деле требуется больше?
2. Выполнение |:tjump| при поиске в файлах меток с помощью |:cstag| нельзя настраивать по своему вкусу (например, нельзя выполнять tselect вместо tjump).

6. Советы по использованию

Поместите в .vimrc следующий код (с исправлением путей, в соответствии с вашими настройками):

if has("cscope")
    set csprg=/usr/local/bin/cscope
    set csto=0
    set cst
    set nocsverb
    " добавляем любую базу данных в текущем каталоге
    if filereadable("cscope.out")
        cs add cscope.out
    " если базы данных не обнаружены, то добавляем 
    " базы, указанные переменной окружения
    elseif $CSCOPE_DB != ""
        cs add $CSCOPE_DB
    endif
    set csverb
endif

Включив опцию 'cscopetag', мы заменяем все вызовы команды :tag на :cstag. Это включает команды :tag, CTRL-] и "vim -t". При этом обычна команда :tag будет выполнять поиск не только в файлах меток, созданных при помощи ctags, но и в базах данных cscope.

Некоторые пользователи предпочитают сохранять обычное поведение команды tag и создают отдельные привязки для доступа к :cstag. Например, можно привязать для доступа к :cstag кнопку CTRL-_ при помощи следующей команды:

map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>

Из запросов к cscope наиболее часто используются поиск всех функций, вызывающих данную функцию, и поиск всех появлений данного символа C. Для этих операций также можно сделать соответствующие привязки:

map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR>
map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR>

Такие привязки для CTRL-] (закрывающая квадратная скобка) и CTRL-\ (обратная косая черта) позволяют помещать курсор над именем функции или символом C и быстро опрашивать базу данных cscope о наличии соответствий.

Вы также можете использовать следующую схему, по мотивам учебника по Vim/Cscope с домашней страницы Cscope (https://cscope.sourceforge.net/):

nmap <C-_>s :cs find s <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>g :cs find g <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>c :cs find c <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>t :cs find t <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>e :cs find e <C-R>=expand("<cword>")<CR><CR>
nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR>
nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR>

" Использование 'CTRL-пробел' с последующей командой поиска
" позволяет разделить окно Vim по горизонтали и показать результаты
" поиска в новом окне.

nmap <C-Space>s :scs find s <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>g :scs find g <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>c :scs find c <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>t :scs find t <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>e :scs find e <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR>
nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR>

" Нажатие CTRL-пробел *дважды* перед указанием команды поиска 
" делит окно Vim по вертикали, вместо горизонтали.

nmap <C-Space><C-Space>s
    \:vert scs find s <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>g
    \:vert scs find g <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>c
    \:vert scs find c <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>t
    \:vert scs find t <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>e
    \:vert scs find e <C-R>=expand("<cword>")<CR><CR>
nmap <C-Space><C-Space>i
    \:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
nmap <C-Space><C-Space>d
    \:vert scs find d <C-R>=expand("<cword>")<CR><CR>

7. Доступность и информация о cscope

Если у вас нет cscope (программа не включена в состав вашей системы), то вы можете загрузить её бесплатно по этому адресу

• https://cscope.sourceforge.net/

Программа выпускается SCO по лицензии BSD.

Если вам требуется более новая версия cscope, то вероятно вам придётся ей купить. Если верить (старой) документации nvi: Исходный код версии 13.3 с неограниченной лицензией можно приобрести за $400 у AT&T Software Solutions. Телефон +1-800-462-8146.

Вы можете также скачать cscope 13.x и mlscope 14.x (многоязычный cscope с поддержкой C, C++, Java, lex, yacc, списков контрольных точек остановки, Ingres и SDL) со страницы программного обеспечения с открытым исходным кодом World-Wide Exptools по адресу:

• https://www.bell-labs.com/project/wwexptools/packages.html

В Solaris 2.x при наличии лицензии на компилятор C вы также должны иметь cscope. Он находится там же, где и компилятор, в /opt/SUNWspro/bin

Разработчики для SGI также могут получить cscope. Ищите Cscope в интернете по адресам:

• https://freeware.sgi.com/index-by-alpha.html
• https://toolbox.sgi.com/toolbox/utilities/cscope/

Второй адрес предназначен для тех, у кого есть пароль для доступа к SGI toolbox.

В сети существует также исходный код более старой версии клона cscope, называемый "cs". По разным причинам эта программе не поддерживается в Vim.

Интерфейс для поддержки cscope в Vim изначально был написан Энди Каном <Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.; (Andy Kahn). При этом была заимствована структура и небольшие участки кода из интерфейса для поддержки cscope в nvi. Сообщения о проблемах с использованием cscope в Vim, предложения, заплатки и т.д. просьба направлять непосредственно к нему.

Версия cscope для Win32 доступна по адресу:

• https://iamphet.nm.ru/cscope/index.html.

Поддержка Win32 была добавлена Сергеем Хоревым <Этот адрес электронной почты защищён от спам-ботов. У вас должен быть включен JavaScript для просмотра.;. Если у вас возникают проблемы, связанные с Win32, обращайтесь непосредственно к нему.