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. You may find using CTags more useful than manually opening and scrolling through files looking for a definition.
Ctags should already be installed on attu. 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, Vim, or Sublime 2/3.
These steps assume you want to use Ctags on the CSE333 Homeworks, but should generalize to other projects.
Important
If you are using the CSE VM, you can install CTags by running sudo yum install ctags.
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.
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 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.
cd to the root directory of your homework project
cd ~/cse333-18sp-ram16/hw1/
Run Etags (Ctags for Emacs) over the project to generate the TAGS file. We use the find command to find all of the .c and .h file in the project, then tell etags to append the tags in those files to the TAGS file. The --declarations flag tells etags to add the function prototypes in the header files to the TAGS file as well. For the CSE333 projects, this should be really fast:
etags $(find . -name \*.[ch]) --declarations
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 source file in Emacs and use the following basic commands:
Keyboard command
Action
M-. <RET>
Jump to the tag underneath the cursor
M-. <tag> <RET>
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. ~/cse333-18sp-ram16/hw1/TAGS). Just hit enter when prompted to do this.
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 he 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 <tag>:
M-x tags-apropos <RET> Tags apropos (regexp): <tag> <RET>
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
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 homework project
cd ~/cse333-18sp-ram16/hw1/
Run Ctags recursively over the entire project to generate the tags file. The last argument in the command tells ctags to append function prototypes to the tags file. This will be really fast for this project.
ctags -R * --c-kinds=+p
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 <tag>
Or, open any source file in Vim and use the following basic commands:
Keyboard command
Action
Ctrl-]
Jump to the tag underneath the cursor
:ts <tag> <RET>
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.
Note
These commands were tested with Sublime 3 but should work with Sublime 2
cd to the root directory of your homework project
cd ~/cse333-18sp-ram16/hw1/
Run Ctags recursively over the entire project to generate the .tags file. The --c-kinds argument in the command tells ctags to append function prototypes to the tags file. This will be really fast for this project. The final flag tells ctags to name the tags file .tags, which Sublime requires.
ctags -R --c-kinds=+p -f .tags
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.
Next, install ctags on Sublime. Open the package manager by going to Preferences->Package Control, then select Install Package from the drop down. Search CTags and then select the first package in the results. This will install the package into Sublime.
Open any source file in Sublime and use the following basic commands:
Keyboard command
Action
Ctrl-t Ctrl-t
Jump to the tag underneath the cursor
Ctrl-Shift-f
Search for a particular tag
Ctrl-t Ctrl-b
Go to the previous definition for the last tag
Ctrl-t Ctrl-r
Rebuild the .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) under the cursor. When there are multiple definitions for the tag, Sublime will display a drop down listing all of the each tag and its corresponding file. You choose which one is jumped to. The second command can be used to search for any tag, regardless of the file that is currently opened. However, it will not jump to the file but instead display search results over the directory you specify when the search bar pops up after triggering the command. The last command is used for when you make substantial changes to the function names/declarations.
Author: Robby Marver (ram16@cs.uw.edu)