=================================== Ctags Tutorial =================================== .. :Info: ... .. :Author: Peter Hornyack .. :Date: $Date .. :Revision: $Revision .. :Description: Tutorial for Ctags. Ctags_ is a tool that makes it easy to navigate large source code projects. It provides some of the features that you may be used to using in Eclipse or other IDEs, such as the ability to jump from the current source file to definitions of functions and structures in other files. Ctags will make it much easier to find the Linux kernel files that you have to modify for your CSE 451 projects. Ctags also supports many languages_ besides C, so you may find it useful for future projects. .. _Ctags: http://ctags.sourceforge.net/ .. _languages: http://ctags.sourceforge.net/languages.html Ctags should already be installed on CSE instructional servers such as ``forkbomb`` and ``attu``, and should also be installed on the `UW CSE Home VM`__ and the `CSE 451 VM`__. Ctags is first run on its own to generate a "tags" file, then it is invoked from within another Linux text editor such as Emacs or Vim. __ http://www.cs.washington.edu/lab/labVMs/homeVMs.shtml __ ../vminfo.html These steps assume you want to use Ctags on the Linux kernel, but should generalize to other projects. .. important:: Before proceeding, double-check that the system you are using has "Exuberant Ctags" installed, rather than the original "Ctags," by running ``ctags --version``. .. tip:: Like all Linux programs, Ctags has a man page (``man 1 ctags``). All of the information in this tutorial, and lots more advanced information, can be found there. Ctags with Emacs =================================== .. tip:: If you are unfamiliar with Emacs, you should go through the Emacs tutorial. Run ``emacs``, then press ``C-h t`` (Ctrl+h, then t) to begin the interactive tutorial. It shouldn't take too long, and it's probably worth your time. You can also check out the online tour_. If you get stuck, press ``C-g`` to cancel pending commands, and exit Emacs by pressing ``C-x C-c``. .. _tour: http://www.gnu.org/software/emacs/tour/ .. admonition:: Disclaimer The author of this tutorial is not an Emacs expert; if you notice potential flaws or improvements, please contact the class TAs and they can update this tutorial. #. ``cd`` to the root directory of your Linux kernel code, e.g.:: cd /cse451/user/project1/linux-2.6.38.2/ #. Run Etags (Ctags for Emacs) over the kernel to generate the ``TAGS`` file. ``etags`` will overflow its stack if called recursively over the entire kernel, so we use the ``find`` command to find all of the ``.c``, ``.h``, and ``.S`` (assembly) files in the kernel, then tell ``etags`` to append the tags in those files to the ``TAGS`` file. For Linux 2.6.38, this should only take a minute or so:: find . -type f -iname "*.[chS]" | xargs etags -a .. note:: You may see messages like "Warning: cannot open source file '...' : Permission denied" while etags is building the tags file. These warnings can be ignored. #. Open any Linux source file in Emacs and use the following basic commands: ===================== ============================================== Keyboard command Action ===================== ============================================== ``M-. `` Jump to the tag underneath the cursor ``M-. `` Search for a particular tag ``C-u M-.`` Find the next definition for the last tag ``M-*`` Pop back to where you previously invoked "M-." ===================== ============================================== .. important:: The first time you run an Etags command within Emacs, you may have to specify the location of your ``TAGS`` file (i.e. ``/cse451/.../linux-2.6.38.2/TAGS``). Say yes when prompted to load the really big tags file. The first command is probably the one you will use most often: it jumps to the definition of the tag (function name, structure name, variable name, or pretty much anything). The second command can be used to search for any tag in the ``TAGS`` file, regardless of the file you are currently viewing. Sometimes Etags will find multiple definitions for a given tag; when this is the case, use the third command to jump through the possible definitions until you find the one that you want. Finally, use the fourth command to jump back up in the tag "stack." You'll probably find that for some tags (common structures, for example), Etags finds hundreds or thousands of uses in the code, and jumping through them (with the third command above) to try to find the original definition is useless. In this case, you can run the following two commands to list all of the uses of a given ````:: M-x tags-apropos Tags apropos (regexp): This will display a list of the tag definitions in another buffer. Switch to the new buffer (``C-x o``), scroll through the list of definitions to the one that you want, then press Enter to open the file. When you're done, instead of jumping back up in the tag stack, close the new buffer (``C-x k``). To switch back to your original buffer and expand it, use ``C-x o`` to switch to it, then ``C-x 1`` to expand. .. note:: Even the list of all definitions given by ``tags-apropos`` may be too large to find the definition that you're looking for. This is mostly a problem for structs (``struct inode``, for instance) that are used frequently in the kernel. You should still find Etags useful for jumping to function definitions and less-commonly-used structs. Ctags for Vim appears to do a better job of separating "definitions" from "uses" in its tags file, so this is less of a problem for Vim; for Emacs, there may be other ways to mitigate this problem (see `this page`__, for example). Alternatively, you may wish to use cscope_ to find function and structure definitions, or just use the third step of the Vim instructions below. __ http://stackoverflow.com/questions/3124567/tags-in-emacs-with-a-large-codebase .. _cscope: tutorial_cscope.html Ctags with Vim =================================== .. note:: These commands were tested with Vim (7.2), but will likely work with Vi or other Vi emulators as well. #. ``cd`` to the root directory of your Linux kernel code:: cd /cse451/user/project1/linux-2.6.38.2/ #. Run Ctags recursively over the entire kernel to generate the ``tags`` file. For Linux 2.6.38, this should only take a minute or so:: ctags -R * .. note:: You may see messages like "Warning: cannot open source file '...' : Permission denied" while ``ctags`` is building the tags file. These warnings can be ignored. #. To search for a specific tag and open Vim to its definition, run the following command in your shell:: vim -t #. Or, open any Linux source file in Vim and use the following basic commands: ===================== ============================================== Keyboard command Action ===================== ============================================== ``Ctrl-]`` Jump to the tag underneath the cursor ``:ts `` Search for a particular tag ``:tn`` Go to the next definition for the last tag ``:tp`` Go to the previous definition for the last tag ``:ts`` List all of the definitions of the last tag ``Ctrl-t`` Jump back up in the tag stack ===================== ============================================== The first command is probably the one you will use most often: it jumps to the definition of the tag (function name, structure name, variable name, or pretty much anything) under the cursor. The second command can be used to search for any tag, regardless of the file that is currently opened. If there are multiple definitions/uses for a particular tag, the ``tn`` and ``tp`` commands can be used to scroll through them, and the ``ts`` command can be used to "search" a list for the definition you want (useful when there are dozens or hundreds of definitions for some commonly-used struct). Finally, the last command is used to jump back up in the tag stack to the location you initiated the previous tag search from. ----------------------------------------------------------------------------- Author: Peter Hornyack (pjh@cs)