*if_cscop.txt* Pour Vim version 6.2c.
MANUEL DE REFERENCE DE VIM de Andy Kahn
*cscope**Cscope*
Ce document explique comment utiliser l'interface Vim de cscope.
Cscope est un outil comme ctags, mais voyez-le plutôt comme un ctags sous
amphétamines car il en fait beaucoup plus. Dans Vim, sauter au résultat d'une
recherche de cscope est aussi aisé que de sauter à n'importe quel marqueur
issu de ctags; ce résultat est sauvé sur la pile de marqueurs ctags de sorte
qu'avec la bonne redéfinition de clavier, vous pouvez sauter d'avant en arrière
entre les fonctions comme vous le faites normalement avec |tags|.
1. Introduction à cscope |cscope-intro|
2. Commandes liées à cscope |cscope-commands|
3. Options de cscope |cscope-options|
4. Utiliser cscope dans Vim |cscope-howtouse|
5. Limitations |cscope-limitations|
6. Suggestions |cscope-suggestions|
7. Disponibilité & Information |cscope-info|
Disponible sur Unix et Win32 seulement.
{Vi ne dispose d'aucune de ces commandes}==============================================================================
1. Introduction à cscope *cscope-intro*
Le texte suivant est tiré d'une version de la page de man de cscope:
-----
Cscope est un outil interactif orienté écran qui vous aide à:
Apprendre comment un programme C travaille sans vous déplacer sans
cesse à travers un épais listing.
Localiser la section de code à changer pour corriger un bug sans avoir
à connaître le programme complet.
Examiner l'effet d'un changement envisagé, comme d'ajouter une occurence
à une variable énumérée.
Vérifier qu'un changement a bien été appliqué dans tous les fichiers
sources, comme d'ajouter un argument à une fonction existante.
Renommer une variable globale dans tous les fichiers sources.
Changer la valeur d'un symbole du préprocesseur dans des lignes
sélectionnées d'un fichier.
Il est conçu pour répondre à des questions comme :
Où ce symbole est-il utilisé?
Où est-il défini?
Où cette variable a-t-elle pris cette valeur?
Quelle est la définition de ce symbole global?
Où est cette fonction dans les fichiers sources?
Quelles sont les fonctions qui appellent une fonction donnée?
Quelles sont les fonctions qui sont appelées par celle-ci?
D'où provient le message "out of space"?
Où est ce fichier dans l'aborescence des répertoires?
Quels sont les fichiers qui incluent ce fichier d'en-tête?
cscope répond à ces questions à partir d'une base de données de symboles
qu'il construit la première fois qu'il est utilisé sur les fichiers sources.
Lors d'un appel ultérieur, cscope reconstruit la base de données seulement si
un ou plusieurs des fichiers sources a changé ou que leur liste a changé.
Quand la base de données est reconstruite, les données pour les fichiers
inchangés sont copiées depuis l'ancienne base, ce qui rend la
reconstruction beaucoup plus rapide que la construction initiale.
-----
Quand cscope est appelé normalement, vous obtenez un écran de sélection vous
permettant de définir et lancer une requête pour une des questions ci-dessus.
Néanmoins, une fois qu'une correspondance a été trouvée pour votre demande et
que vous avez ouvert votre éditeur sur le fichier contenant cette correspondance,
vous ne pouvez simplement sauter de marqueur en marqueur comme vous le feriez
normalement avec les commandes Ctrl-] ou :tag de vi.
L'interface cscope de Vim est réalisée en invoquant cscope par son interface
ligne, et en analysant la sortie renvoyée par une requête. Le bilan final
est que les résultats de la requête cscope sont empilés comme des marqueurs
ctags habituels, de sorte que vous pouvez sauter jusqu'à eux exactement comme
vous le feriez normalement (par Ctrl-] or :tag) et ensuite retourner en libérant
la pile des marqueurs par Ctrl-T. (Néanmoins, notez s'il vous plaît que vous ne
sauterez pas réellement à un marqueur cscope en faisant Ctrl-] ou :tag
sans avoir redéfini ces commandes ou positionné une option.
Voyez les sections restantes sur le fonctionnement de l'interface cscope et
les suggestions d'utilisation.
==============================================================================
2. Commandes connexes *cscope-commands**:cscope**:cs**:scs**:scscope**E259**E262**E561**E560*
On accède à toutes les commandes à travers des sous-options de la commande
cscope principale ":cscope". L'abréviation la plus courte en est ":cs".
La commande ":scscope" fait pareil et, de plus, partage la fenêtre.
Les sous-commandes disponibles sont:
*E563**E564**E566**E568**E569**E622**E623*
add : Ajoute une nouvelle connexion à la base cscope.
USAGE :cs add {file|dir} [pre-path][flags][pre-path] est le chemin utilisé avec la commande cscope -P.
[flags] sont des flags additionnels que vous pouvez passer à cscope.
EXEMPLES
:cscope add /usr/local/cdb/cscope.out
:cscope add /projects/vim/cscope.out /usr/local/vim
:cscope add cscope.out /usr/local/vim -C
*E565**E567*
find : Requête à cscope. Toutes les options de requête cscope sont
disponibles sauf l'option #5 ("Changer cette expression grep").
USAGE :cs find {querytype}{name}{querytype} correspond aux numéros d'interface ligne de
cscope ou à des commandes nvi par défaut:
0 or s: Trouver un symbole de langage C
1 or g: Trouver une définition
2 or d: Trouver les fonctions appelées par une fonction
3 or c: Trouver les fonctions qui appellent une fonction.
4 or t: Trouver une chaîne de caractères
6 or e: Trouver une expression compatible egrep
7 or f: Trouver un fichier
8 or i: Trouver les fichiers #incluant un fichier
EXEMPLES
:cscope find c vim_free
:cscope find 3 vim_free
Ces deux exemples réalisent la même requête.
:cscope find 0 DEFAULT_TERM
<
L'exécution de cet exemple sur le code source de Vim 5.1 produit
la sortie suivante:
Cscope tag: DEFAULT_TERM
# line filename / context / line
1 1009 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"amiga"
2 1013 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"win32"
3 1017 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"pcterm"
4 1021 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"ansi"
5 1025 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"vt52"
6 1029 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"os2ansi"
7 1033 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"ansi"
8 1037 vim-5.1-gtk/src/term.c <<GLOBAL>>
# undef DEFAULT_TERM
9 1038 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"beos-ansi"
10 1042 vim-5.1-gtk/src/term.c <<GLOBAL>>
#define DEFAULT_TERM (char_u *)"mac-ansi"
11 1335 vim-5.1-gtk/src/term.c <<set_termname>>
term = DEFAULT_TERM;
12 1459 vim-5.1-gtk/src/term.c <<set_termname>>
if (STRCMP(term, DEFAULT_TERM))
13 1826 vim-5.1-gtk/src/term.c <<termcapinit>>
term = DEFAULT_TERM;
14 1833 vim-5.1-gtk/src/term.c <<termcapinit>>
term = DEFAULT_TERM;
15 3635 vim-5.1-gtk/src/term.c <<update_tcap>>
p = find_builtin_term(DEFAULT_TERM);
Enter nr of choice (<CR> to abort):
La sortie montre plusieurs éléments d'information
1. Le numéro de marqueur (il y en a 15 dans cet exemple).
2. Le numéro de ligne où le marqueur est trouvé.
3. Le nom de fichier où le marquer est trouvé.
4. Le contexte du marqueur (par ex., global, ou le nom des fonctions).
5. La ligne elle-même.
help : Donne un synoptique résumé.
USAGE :cs help
*E260**E261*
kill : Tue une connection à cscope (ou tue toutes les connexions à cscope).
USAGE :cs kill {num|partial_name}
Pour tuer une connexion à cscope, le numéro de connexion ou un nom
partiel doit être spécifié. Un nom partiel est simplement toute
partie du chemin de la base cscope. A utiliser avec précaution!
Si le numéro de connexion est -1, toutes les connexions cscope seront
tuées.
reset : Réinitialise toutes les connexions à cscope.
USAGE :cs reset
show : Montre les connexions à cscope.
USAGE :cs show
*:cstag**E257**E562*
Si vous utilisez à la fois cscope et ctags, |:cstag| vous permet de choisir
l'un ou l'autre avant de faire le saut. Par exemple, vous pouvez choisir de
chercher une correspondance d'abord dans vos bases de données cscope, et, en
cas d'échec, rechercher les marqueurs ctags.
L'ordre dans lequel ceci a lieu est déterminé par la valeur de |csto|.
Voir |cscope-options| Pour plus de détails .
|:cstag| réalise l'équivalent de ":cs find g" sur l'identificateur lors d'une
recherche sur les bases cscope.
|:cstag| réalise l'équivalent de |:tjump| sur l'identificateur lors d'une
recherche sur les fichiers ctags.
==============================================================================
3. Options de Cscope *cscope-options*
Utiliser la commande |:set| pour positionner toutes les options de cscope.
Idéalement, vous devriez le faire dans un de vos fichiers de démarrage (p.ex., .vimrc).
Certaines options liées à cscope ne sont valides qu'à l'intérieur de |.vimrc|.
Les positionner après que vim a démarré n'aura aucun effet!
*cscopeprg**csprg*'cscopeprg' spécifie la commande pour exécuter cscope. La valeur par défault
est "cscope".
Par exemple:
:set csprg=/usr/local/bin/cscope
*cscopetag**cst*
Si 'cscopetag' est positionné, les commandes ":tag" et CTRL-] aussi bien que "vim -t"
utiliseront toujours le comportement |:cstag| au lieu de la valeur par défaut :tag .
Effectivement, en positionnant 'cst', vous chercherez toujours dans vos bases cscope
et dans vos fichiers ctags. La valeur par défaut est off.
Exemples:
:set cst
:set nocst
*cscopetagorder**csto*
La valeur de 'csto' détermine l'ordre dans lequel |:cstag| réalise une
recherche. Si 'csto' est positionné à zéro, on cherche d'abord dans les
bases cscope, puis dans les fichiers de marqueurs (tags) si cscope n'a trouvé
aucune correspondance. Si 'csto' est positionné à 1, on cherche dans les fichiers
de marqueurs avant les bases cscope. La valeur par défaut est zéro.
Exemples:
:set csto=0
:set csto=1
*cscopeverbose**csverb*
Si 'cscopeverbose' n'est pas positionné (état par défaut), aucun message ne
sera imprimé rendant compte d'un succès ou d'un échec lors de l'ajout d'une
base cscope. Idéalement, vous devriez invalider cette option dans votre fichier
|.vimrc| avant d'ajouter une base cscope, et le valider après les ajouts.
A partir de là, quand vous ajoutez des bases de données depuis Vim, vous
obtiendrez un message espéré utile en cas d'échec d'ajout de la base.
Exemples:
:set csverb
:set nocsverb
*cscopepathcomp**cspc*
La valeur de 'cspc' détermine combien de composants d'un chemin de fichier
afficher. Avec la valeur par défaut de zéro, le cehmin entier est affiché.
La valeur 1 n'affichera que le nom du fichier sans chemin. Les autres valeurs
affichent ce nombre de composants .
Exemple:
:set cspc=3
affichera les trois derniers composants du chemin de fichier, dont le nom de
fichier lui-même. ( "/a/b/c/d/f/g/h.c" sera affiché "f/g/h.c" )
==============================================================================
4. Utilisation de cscope dans Vim *cscope-howtouse*
La première chose dont vous ayez besoin eest de créer une base de données
cscope pour vos fichiers-sources. Pour le cas le plus basique, faire simplement
"cscope -b". Merci de vous référer à la page de man de cscope pour plus de
détails.
Suppposant que vous avez une base cscope, vous devez "ajouter" la base à Vim.
Ceci établit une connexion à cscope et en donne l'accès à Vim.
Vous pouvez faire ceci dans votre ficheir .vimrc , ou le faire manuellementrmstrA3XX.dd.gz
après le démarrage de Vim. Par example, Four ajouter la base "cscope.out",
vous devriez faire :
:cs add cscope.out
Vous pouvez vérifire le résultat en exécutant ":cs show".
Ceci produira une sortie ressemblant à :
# pid database name prepend path
0 28806 cscope.out <none>
Note:
Du fait de limitations des bibliothèques Microsoft, la version Win32 donne -1
au lieu du vrai PID.rmstrA3XX.dd.gz
Une fois qu'une connexion cscope est établie, vous pouvez faire des requêtes à
cscope et les résultats vous seront affichés. Les requêtes sont construites
en faisant usage de la commande ":cs find".
Par exemple:
:cs find g ALIGN_SIZE
Ceci peut devenir un peu encombrant car on finit avec un volume significatif de frappe.
Heureusement, on peut contourner celà à l'aide de raccourcis-claviers.
Voir |cscope-suggestions| pour des suggestions.
Si les résultats ne retournent qu'une correspondance, vous y serez
immédiatement envoyé. S'il y en a plus d'une, vous obtiendree un écran de
sélection pour choisir celle où vous voulez vous rendre. Après avoir sauté à
ce nouvel emplacement, frappez simplement Ctrl-T simply hitour retourner au
précédent .
rmstrA3XX.dd.gz
==============================================================================
5. Limitations *cscope-limitations*
Le support de csope pour Vim d'est disponible que sur les systèmes diposant
des appels système suivants :: fork(), pipe(), execl(), waitpid().
Donc, pricipalement limité aux systèmes de la famille Unix.
Ce support est fourni de plus sous Win32.
Pour plus d'information et une version Win32 de cscope :
http://iamphet.nm.ru/cscope/index.html
Il existe deux limitations codées en dur :
1. Le nombre maximal de connexions cscope est de 8. Il vous en faut
réellement plus ?
2. Faire |:tjump| quand |:cstag| cherche en fichiers de marqueurs n'est
pas configurable
(par ex. vous ne pouvez faire un tselect à la place).
==============================================================================
6. Suggestions d'utilisation *cscope-suggestions*
Mettre ces entrées dans votre .vimrc
(ajuster les chemins d'accès à votre installation ):
if has("cscope")
set csprg=/usr/local/bin/cscope
set csto=0
set cst
set nocsverb
" add any database in current directory
if filereadable("cscope.out")
cs add cscope.out
" else add database pointed to by environment
elseif $CSCOPE_DB != ""
cs add $CSCOPE_DB
endif
set csverb
endif
En positionnant 'cscopetag', nous remplaçons toutes les instances de la
commande :tag par :cstag. Ceci inclut :tag, Ctrl-], et "vim -t". En faisant
ainsi, la commande tag habituelle cherche non seulement dans les fichiers de
marqueurs générés par la commande ctags, mais aussi dans les bases de données
générées par cscope.
Certains utilisateurs peuvent vouloir conserver le comportement standard et
avoir un raccourci différent pour accéder à :cstag. Par exemple, on pourraitrmstrA3XX.dd.gz
redéfinir Ctrl-_ (underscore) en :cstag avec la commande suivante:
map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>
Une paire de requêtes cscope d'usage très général (utilisant ":cs find") est
de trouver toutes les fonctions appelant une certaine fonction et de trouver
toutes les occurrences d'un symbol C particulier. Vous pouvez utiliser ces
redéfinitions :
map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR>
map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR>
Ces redéfinitions pour Ctrl-] (crochet droit) and Ctrl-\ (backslash) vous
permettent de placer votre curseur sur le nom de la fonction ou le symbole C
et rapidement appeler la requête cscope de recherche de toutes les correspondances.
Vous pouvez aussi utiliser le schéma suivant, inspiré par le tutoriel Vim/Cscope,
que vous trouverez à la page d'accueil de cscope (http://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>rmstrA3XX.dd.gz
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>rmstrA3XX.dd.gz
nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR>
" Si on frappe 'CTRL-spacebar' avant la frappe de recherche,
" on sépare horizontalement la fenêtre Vim en deux, avec les
" résultats de recherche dirigés vers la nouvelle fenêtre.
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>
" Frapper *deux fois* CTRL-space avant la frappe de recherche
" crée un partage vertical de la fenêtre Vim au lieu d'horizontal.
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. Disponibilité de Cscope et information *cscope-info*
Si vous n'avez pas déjà cscope (car il n'était pas avec votre compilateur
ou distribution d'OS), vous pouvez le télécharger librement à:
http://cscope.sourceforge.net/
Il est réalisé sous license BSD.
In April, 2000, thanks to the Santa Cruz Operation, Inc. (SCO) (since merged
with Caldera), the code for Cscope was open sourced under the BSD license.
Si vous voulez une version plus récente de cscope, vous devrez probablement
l'acheter. Selon la (vieille) documentation nvi:
Vous pouvez acheter une version source 13.3 avec une license sans
restriction pour 400 USD à AT&T Software Solutions en appelant (USA) +1-800-462-8146.
Aussi, vous pouvez télécharger cscope 13.x et mlcscope 14.x (multi-lingual cscope
qui supporte C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL)
depuis le page de packages "World-Wide Exptools Open Source" à :
http://www.bell-labs.com/project/wwexptools/packages.html
Dans Solaris 2.x, si vous avez la license du compilateur C, vous avez aussi
cscope. Les deux sont dans /opt/SUNWspro/bin.
Les développeurs sous SGI peuvent aussi l'obtenir. Un fichier tardist peut
être trouvé à :
ftp://ftp.openage.com/pub/Sgi/Binaries/Cscope-13_3_tardist.gz
https://toolbox.sgi.com/toolbox/utilities/cscope/
Le deuxième lien est pour ceux qui ont un mot de passe pour la toolbox SGI.
On trouve sur le net la source d'une version plus ancienne d'un clone de
cscope (appelé "cs")
Le support et l'interface de cscope par Vim ont été originalement écrits par
Andy Kahn <ackahn@netapp.com>. La structure initiale (aussi bien qu'un peu
de code) a été adapté de l'interface entre cscope et nvi.
Merci de lui rapporter tout problème, suggestion, patches et autres que vous
rencontrerez ou développerez dans votre usage quotidien de cscope à partir
de Vim.
*cscope-win32*
Pour une version Win32, voir : http://iamphet.nm.ru/cscope/index.html
Le support Win32 a été ajouté Sergey Khorev <khorev@softlab.ru>. Contactez-le
si vous avez des problèmes spécifiques à Win32.
vim:tw=78:ts=8:ft=help:norl: