Ctags Tutorial

Installation

• attu: Ctags should already be installed on attu and ready to use.
• CSE Linux VM: Install Ctags by running the command sudo dnf install ctags from the Terminal.

The Basics

Ctags needs to first be run to generate a "tags" file, then it is invoked from within a text editor to navigate the tags. The sections below are specific to using Ctags on the CSE333 Homework, but the commands will generalize to other C/C++ projects.

Generating the tags file

1. Navigate to the root directory of your homework project (replacing <netid> and <#> appropriately):

   $ cd ~/cse333-23wi-<netid>/hw<#>/

2. Run Ctags recursively over the entire project to generate the tags file (the last argument tells Ctags to append function prototypes to the tags file):

   $ ctags -R * --c-kinds=+p

   You may see messages like Warning: cannot open source file '...' : Permission denied while ctags is building the tags file. These warnings can be ignored.

Using the tags file

You have two options for using the tags file:

1. To search for a specific tag and open vim to its definition, run the following command in your shell:

   $ vim -t <tag>

2. 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.

Generating the tags file

1. Navigate to the root directory of your homework project (replacing <netid> and <#> appropriately):

   $ cd ~/cse333-23wi-<netid>/hw<#>/

2. 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.

   $ etags $(find . -name \*.[ch]) --declarations

   You may see messages like Warning: cannot open source file '...' : Permission denied while etags is building the tags file. These warnings can be ignored.

Using the tags file

Open any source file in emacs and use the following basic commands:

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 <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.

Generating the tags file

1. Navigate to the root directory of your homework project (replacing <netid> and <#> appropriately):

   $ cd ~/cse333-23wi-<netid>/hw<#>/

2. 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. The final flag tells ctags to name the tags file .tags, which Sublime requires.

   $ ctags -R --c-kinds=+p -f .tags

   You may see messages like Warning: cannot open source file '...' : Permission denied while ctags is building the tags file. These warnings can be ignored.

Using the tags file

First, you will need to install ctags on Sublime (just once).

1. Open the package manager by going to Preferences→Package Control.
2. Select Install Package from the dropdown menu.
3. Search Ctags and then select the first package in the results.

Open any source file in Sublime and use the following basic commands:

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 dropdown menu 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.