My Favorite Code Development Tools, Part 2:Cscope and Doxygen

To continue my previous post about my favorite code development tools, I'll share two tools I've recently come across that greatly enhance text-mode code development: Doxygen and Cscope.

I learned more about these tools while attempting to familiarize myself with the new version of the Sniper Simulator that was released at the beginning of December. For architectural simulators such as Sniper and gem5, being the fairly large code projects that they are, the task of wrapping one's head around the code sections of interest - or even finding those codes at all - can be a daunting task. In the process of navigating the source code and trying to overcome this hurdle, I discovered two tools that assist in the process of code comprehension through static code analysis.

Although many are familiar with Doxygen, some of its less prominent features may remain unknown to many users. While most probably know that it will generate documentation from code that has been commented, just as useful is its ability to generate other information about code even when it is entirely uncommented. The feature that has become very useful for me recently has been its ability to generate call graphs. To enable this, in your Doxygen configuration file, set HAVE_DOT, CALL_GRAPH, and CALLER_GRAPH to "YES". Doing this will tell Doxygen to generate nice graphs using the Dot program, which can be used to navigate the code by determining for each function f which functions f calls and which functions are called by f. You must have the Dot program installed. (Note that Dot is a very useful program in its own right.)

Viewing the call graphs from Doxygen requires a program with a graphical interface such a browser to view the generated graphs. For working in text mode, another option for navigating code based on function calls is Cscope. The interface of Cscope is similar to that of ctags and omnicpp, which were mentioned in the previous post. There is a plugin for Vim available which provides the Cscope features. Cscope provides a number of incredibly useful features for code navigation - and all in text mode. A series of keystrokes will display a list of functions that call the function under the cursor, for example. There is a tutorial for using Cscope with Vim here.

Since Doxygen and Cscope provide information about the program without actually running it, these are static analysis tools. Additional information about applications can be provided by analyzing them dynamically, or at run-time. Some dynamic code analysis tools that are useful are gprof and gdb. I will plan to discuss these in a future post. Another tool worth mentioning about which I learned recently is the -finstrument-functions switch for gdb, which is used with Dot to generate dynamic call graphs. A tutorial explaining how to use this switch is available here.

My Favorite Code Development Tools:vim, byobu, ctags, and omnicpp

Simulator development is a common practice in the world of computer architecture, so it is important for one to keep his code development skills sharp. I recently have been introduced to a new development tool, so I thought this would be a good time to highlight my four favorite tools for code development.

First, I should say that I am a proponent of text mode development. There are several advantages to working without a GUI. The most important, in my opinion, are that:

1. From a computer with only a simple ssh client, such as PuTTy, one can log into a machine remotely and get work done.
2. There is less to configuration involved with text mode in comparison to running with the X server. This makes for easier configuration, fewer things to go wrong, and less overhead.
3. Frequently during OS upgrades or fresh OS installs, one will run into problems with the X server. To fix these problems, being able to work without the GUI is a very useful tool.
4. You may want to run a machine without a display connected to it for some reason (displays cost money, they take up space, etc.). If you know how to run in text mode, you can connect to the machine remotely over a network without a display.

---

1. vim

For editing human-readable files in text mode, I generally use vim. I just happened to get exposed to vim before emacs, so this is what I've gotten used to. There are many tutorials online with using vim. Although learning the commands can take some time, once one gets used to using it, vim becomes an efficient way of editing files. I actually prefer it to other editors with GUIs. I find that this principle is true of many command-line tools, such as LaTeX and others. Although the learning processing may take a long time, once one is acclimated to the tool, he will prefer it to the more "user-friendly" alternatives. Vim is available in Ubuntu in the package "vim".

2. byobu

The next tool is byobu. This is a wrapper around the program "screen." Screen allows the user to maintain persistent sessions on a remote machine. So, when the connection is lost due to the client machine crashing or the network going down, the user's programs on the server continue to run, and the session can be resumed from where the user left off. Byobu simply adds some bells and whistles to screen. It shows various indicators of system metrics, as well as nice interface for managing multiple sessions at a time. Byobu is especially useful when running long simulations. If the connection gets lost or you need to reboot the client machine, you can leave the simulation running. Multiple sessions are also useful for editing multiple files at a time. Byobu is available in Ubuntu in the package "byobu".

3. ctags

When editing code in a large project (which is a frequent task when working with and extending open source simulators), it is common that one needs to jump to the implementation of a function from the location at which it is being called. The ctags tool allows for this, even when the implementation is in another file. There is even a stack of files maintained, so one can jump to the implementation from the function call, and then jump back to the calling location later. I am new to this tool, so I have run into a couple of annoyances with ctags. For example, if a class is a subclass that inherits functions from another class, ctags can get confused about where to jump to. There may be a simple solution to this, but I am still learning. Even with these issues, navigating code with ctags is unspeakably easier than without it. Ctags is available in Ubuntu in the package "ctags". Ctags is simple to use. Here is a tutorial.

4. omnicpp

After getting exposure to "Intellisense" in Microsoft's Visual Studio, I was almost inclined to say that I preferred code development in VS over Linux. Intellisense gives the programmer a list of the members of a class after typing the name of an object that is an instance of that class. Well, I recently came across the tool "omnicpp," which provides this functionality in vim in text mode! I am new to this tool, so I can't comment extensively on how well it works. But from my initial exposure, I am very pleased. It is available for download at vim.org here. Installation instructions are available here.

Note that I have recently started tinkering a bit with KDevelop, a GUI-based IDE for Linux. It is worth mentioning here that code completion is available in KDevelop, and instructions for using it are available here and here. Although I am not totally opposed to using a GUI for development, I think that text mode development is an indispensable tool, while GUI-based development is not.

Elements of a Good Computer Architecture Paper

One primary activity on this blog will be posting summaries of papers I find particularly interesting. In my research experience over the years, I have found that, in general, a good computer architecture paper will include the following elements:

1. An overview of the status of the field of study with a focus on the areas relevant to the specific topic of the paper. An explanation of the problem that has been addressed.
2. A discussion of the value of ideas based on the primary metrics of performance, power, and energy.
3. Consideration to hardware and software issues with a specific focus on the intersection between the two (i.e. the microarchitecture, the ISA, or both).
4. References to good papers containing prior related work and a brief overview of those that involve work that address the same problem as that of the current paper.
5. A justification, through clear explanation, for any complexity inherent within the ideas presented.
6. An explanation of the techniques used to gather data for the analyses through which conclusions are drawn.
7. A presentation of how the paper has advanced the field by addressing the stated problem.

Sniper Initialization Call Graph

Here is the call graph I created for the initialization sequence for the Sniper simulator.

gem5 Initialization Call Graph

Here is the call graph I created for the initialization sequence for the gem5 simulator.