Copyright © 2012 David Röthlisberger.
This guide is released under the
GNU Free Documentation License.

Basic Unix/C workflow

This chapter uses the source code of the GNU Readline library as an example. You can grab it (by cding to a directory of your choice and then issuing the shell command git clone git://git.savannah.gnu.org/readline.git[1]) or follow along using your own C or C++ code.

c-mode

If you accidentally invoke C-x C-f again, or any other command that is expecting some kind of input from you, remember you can cancel by making sure the minibuffer has focus and pressing C-g.

Because this is a C source file, Emacs has automatically activated an editing mode called “c-mode”, which provides some custom keybindings and knowledge of C indentation rules and syntax highlighting. We will study c-mode in depth later on.

shell

This creates a new buffer running the shell specified by environment variable SHELL.[2] The buffer is called *shell* (the asterisks are part of the name, so you have to type them when switching to this buffer with C-x b).

The *shell* buffer’s editing mode is shell-mode. You can run almost any shell command inside shell-mode; the exceptions are anything that requires real terminal support, like pagers (less) and curses-based programs. You lose bash’s readline completion and any custom bash-completion scripts, or the equivalent in your shell of choice (though Emacs provides its own command history and tab-completion). For these reasons, I tend to have a real terminal running (outside of Emacs) for some tasks, as well as a shell in Emacs. (Trying to do everything in Emacs reaches a point of diminishing returns.)

The big advantage of shell-mode is that all output is available for you to search through, copy, paste, and otherwise act upon, all with the standard Emacs commands; you don’t have to move your hand to the mouse just to select some text.

Shell-mode adds a number of keybindings:

(For now, don’t bother reading the help text about customization—the variables and hooks shell-mode provides to modify its behavior. After shell-mode comes documentation for all the active minor modes; you don’t need to read that either.)

Of particular interest are pressing RET or C-c RET on a previous input line; C-<up> and C-<down> (or M-p and M-n) to cycle through previous commands; and M-x dirs.

eshell

If you’re not particularly wedded to bash or any other shell, instead of shell you might consider using eshell, a shell totally implemented in Emacs lisp. Among other advantages, running eshell on Windows doesn’t require Cygwin; you can enter lisp code or any Emacs command by name directly at the shell prompt; and you can redirect command output to the Emacs clipboard or to any open Emacs buffer.

I don’t use eshell myself, but many do. For now it might be simplest to stick with the shell you know (running inside Emacs).

ansi-term

The final option for running a shell under Emacs is ansi-term. This is a full terminal emulator, and it will pass most key presses directly to the program running in the terminal. This includes TAB, so it will be the shell, not Emacs, performing tab-completion for you.

C-x and C-c are still processed by Emacs; for M-x you’ll have to type C-x M-x. You can switch from “raw” character mode to “line” mode to get normal Emacs behavior back (e.g. for moving the cursor around so you can copy some previous output); nothing will be sent to the terminal until you press return.

To find out how, you can’t use C-h m because C-h is passed to the shell (where it probably means backspace). Instead of C-h use <f1>, or invoke describe-mode by name.

shell-command

To run a one-off shell command without opening a full shell buffer, use shell-command (M-!).

shell-command-on-region (M-|) is similar but sends the current region to the shell command’s standard input. Let’s use it to calculate the line count of rl.c’s main function:

If you forget the names of these commands, type M-x shell TAB TAB.

The help for this one is pretty long, but the important information is near the top. Ignore the paragraph on coding systems, and everything about noninteractive arguments (which are for calling this function from lisp scripts, as opposed to interactively like we have been doing).

The sentence “Prefix arg means replace the region with [the output of the shell command]” refers to providing a numeric argument to the command. You’ll remember numeric arguments from the tutorial. In this case the value of the argument doesn’t matter, so M-2 M-| or C-u M-| will do.

sh-mode

If you are not particularly comfortable with shell scripting, I apologize for dumping you into a 12,000-line programmatically-generated script, but it’s the closest one I had for an example.

The mode for editing shell scripts is sh-mode (as opposed to shell-mode for running an interactive shell session, which we’ve seen already). If Emacs didn’t figure out that the file is a shell script (perhaps it’s missing the hash-bang interpreter directive on the first line) you can enter sh-mode with, you guessed it, M-x sh-mode.

I don’t really have much to say about sh-mode. It will do syntax highlighting and indentation for a variety of shells; and it provides keybindings to run the script, and to insert certain shell constructs (case statements, for loops, etc.) with the correct syntax for the current shell. If Emacs gets it wrong (again with the missing hash-bang!) you can tell Emacs which shell to use.

By now you know where to find out how.

Info documentation

Assuming that the Info documentation for the bash shell is correctly installed on your system (which should be the case for any Linux or OS X system, at least) you will see an Info window showing the bash manual at the very line for the test command.

As usual, C-h m will show all the keybindings for info mode. For once, though, don’t bother remembering all the keybindings, nor reading through the rather tedious Info tutorial. All you need to know is:

• SPC and DEL for scrolling; when you get to the end of a “node” (a page or section), pressing SPC again goes to the next node in the sequence. I must warn you, DEL is sometimes buggy when you reach the first node in a chapter.
• l (the letter ell) moves back in history.
• u or ^ moves up to the nearest enclosing table of contents. Pressing u repeatedly will get you to the main Info directory containing all the Info manuals found on your system. (The Emacs-related manuals are also available on the web.)
• Use the usual mechanisms for searching (C-s and C-r); when you reach the end of a node, pressing C-s again will continue searching through the rest of the manual.

As you can see from the Info directory, there are many Info manuals, including manuals for Emacs itself, an Emacs Lisp reference and intro, and manuals for the more complex Emacs editing modes like cc-mode.

I can’t overstate how useful the Info documentation is. If you’re maintaining a Makefile you can look up the meaning of esoteric symbols like $@. Need to do some socket programming? In a later chapter we will install the Info manuals for glibc (the GNU implementation of the Unix standard library).

info-lookup-symbol uses the mode of the current buffer to determine which manual to look in. Sometimes it can’t tell, so it will prompt you: Enter sh-mode or makefile-mode or c-mode or whatever (TAB to show all possible options). With a C-u prefix, info-lookup-symbol will always ask.

compile

(C-x 1, which you learned in the tutorial, hides all windows except the currently selected one; C-x 0 does the opposite.)

Anyway, back to the *compilation* window. Compilation-mode has its own special keybindings, of course:

The compilation command is run from the buffer’s associated directory; normally this is the directory containing the buffer’s file. To run make on a different Makefile, you could specify the -C (--directory) or -f (--makefile) make options; or you can change the buffer’s default directory with M-x cd before M-x compile.

rgrep

To search for all occurrences of a string (or regular expression) in a project, use rgrep.[4] This puts the matches in a new buffer, which you can navigate just like the compilation buffer (in fact, grep-mode inherits its functionality and keybindings from compilation-mode).

You can control the exact grep command line used: Read the documentation for rgrep to find out how, or use grep or grep-find instead. The C-h f documentation is an adequate reference, but the Info manual (C-h F rgrep) provides a better introduction.

vc

Emacs has a set of commands, all starting with “vc-”, that provide a consistent interface to various version control systems. The readline files we are using in this tutorial are in a git repository, but the basic commands are the same for subversion or cvs. More advanced commands (such as altering repository settings, or pushing and pulling to remote repositories in git and other distributed vc systems) you will still have to do outside of Emacs.

(If you find yourself missing clickable tabs for switching between buffers, remember that C-x b is more scalable—it works better when you have hundreds of buffers open. Later on we will see how to save a lot of typing under C-x b.)

Now for argument’s sake, let’s say we find rl.c’s documentation for the “-u” command-line flag somewhat confusing:

The diff will be shown in diff-mode, which is also used for viewing patch files. diff-mode has some useful tricks—read its documentation when you have a spare minute.

All the vc commands are bound to key sequences starting with C-x v. If you were paying attention when you invoked the diff command by its full name, you may have noticed that Emacs told you the corresponding keybinding.

To commit the file, look into C-x v v (vc-next-action). Or enter vc-dir-mode with C-x v d and find out how to mark files, for performing vc- actions on multiple files at once.

vc has a (long!) section in the Emacs manual.

Personally, I prefer to use the gitk and git gui tools, or git’s command-line interface directly, for adding, staging, committing, reverting, merging, branching. But I do use the Emacs vc-diff and vc-print-log (and vc-annotate!) extensively.

Because vc is limited to the common denominator of the backend systems it supports, people have written custom modes for specific version control systems. Magit is one such mode for git; but as we haven’t yet learned how to install extensions, we’ll stick with vc. Anyway, vc can do a thing or two even magit doesn’t do—have I mentioned vc-annotate?

vc-annotate

A couple of sections ago, I asked you to grep the readline sources for “rl_insert_comment”.

Remember, when switching buffers with C-x b you have to enter the asterisks as part of the buffer name. (Incidentally, the asterisks are for buffers not associated with a file on disk. This is just a convention; you could always rename the *grep* buffer to something without asterisks —see rename-buffer— or save it to disk if you wanted to.)

Let’s find out which release of readline added the Meta-# keybinding:

Of course, annotate is more useful when the commits are more granular and the commit messages are more descriptive, with links to bug tracker entries and so on. But you get the idea.

Right now I don’t expect you to remember all these keybindings, but I do expect you to know how to find them when you need them.

ediff

ediff is a more powerful mode for viewing differences between files or revisions.

This opens a new frame from which you control ediff; always make sure the ediff frame has focus when you’re giving it a command.

When invoking ediff-revision you can supply any two revisions, not just the latest revision and the current working copy. You can also diff any 2 buffers (ediff-buffers) or files (ediff-files).

I suggest you stay away from ediff-directories (if you want to know why, try using it).

etags

etags is a program that indexes source files and creates a TAGS file that Emacs can use to find definitions of variables, functions and types.

The Makefiles of most open-source projects include the TAGS target. For those that don’t, you can use a combination of find, xargs and etags from the shell to generate the TAGS file manually (read the man pages for those tools if you need to).

The etags you just ran was probably the one that shipped with Emacs. There’s an alternate implementation called “Exuberant ctags” that supports more languages. Install it with your package manager (e.g. port or yum install ctags) and call it with ctags -e.

To use a different TAGS file visit-tags-table.

If you’re a C++ programmer, you’ll soon find that ctags/etags is not perfect when it comes to classes and namespaces. As a 90% solution, it’s good enough, most of the time. Hopefully someone will come up with a clang-based indexer sometime soon.

gdb

We’re going to run the rl program under the GNU debugger, gdb.

The compilation should succeed,[5] as long as you haven’t introduced any errors in any of the source files. If you have, you know how to view and back out your changes.

You are now running gdb inside Emacs, so the standard gdb commands apply. Let’s set a breakpoint in the readline function, start the rl program, and when we reach the breakpoint step through a few lines.

Note how Emacs displays the corresponding source file and line in a separate window.

The above commands are all interpreted directly by the gdb program. gdb allows you to abbreviate them to r, p, n, s, bt, and f, respectively. Pressing return on an empty line repeats the previous command—useful for multiple next commands. help displays gdb’s built-in help.

For serious debugging, Emacs can open additional windows showing the current stack frames, breakpoints, local variables and registers. See the Emacs manual for details: C-h r opens the Emacs manual in the Info browser, then search for the chapter titled “GDB Graphical Interface”.

Homework

You may be feeling somewhat overwhelmed at this point. Spend a few days using Emacs as your main editor, painful though it may be, before moving on to the next chapter of this guide. If you’ve forgotten a command I’ve taught you, try to figure it out yourself (use C-h m, C-h a, C-h f, C-h k and C-h F) before looking it up here.

As part of your commitment to learning Emacs, try to run your shell within Emacs as much as possible. (If you need help configuring your shell to work well within Emacs, or configuring Emacs to work well with your shell, we will revisit shell-mode in the “General customization” chapter of this guide.)

Next: cc-mode customization