Sams Teach Yourself Emacs in 24 Hours		ContentsIndex
Hour 19: Programming Utilities		Previous HourNext Hour
Sections in this Hour: Version Control Systems Summary Compiling Programs Q&A Debugging Programs Exercises		Previous SectionNext Section

Hour 19
Programming Utilities

This hour assumes that you have a basic working knowledge of version control system concepts and compilers, as well as of make and debugging programs. In most cases, working with these systems in Emacs is similar to using them from the command line. The difference is that you never need to leave Emacs to do it. This hour covers the following:

• Version control systems

• Compiling programs

• Debugging programs

Careful use of all these features can improve your development for programs written in almost any language, including C/C++, Java, Assembler, and Perl.

Version Control Systems

If you do not have your source code in a version control system, consider using one of the free systems. If you have never used a version control system before, note that it enables you to keep revisions of your source code available, storing only differences. Such a system is ideal for verifying changes; it enables you to go backward through the change-logs to identify bugs that were introduced a long time ago.

If you want to use a version control system and have not done so before, check to see if you have RCS or SCCS installed. If neither of these systems is available, RCS is very easy to install. To enable your current source code directory for RCS, simply create an RCS directory. For SCCS, create an SCCS directory. For the purposes of this section, it is assumed that you are using RCS, unless it is otherwise specified.

The package pcl-cvs.el also handles CVS repository access, and might be preferable to the minimal support that is available by default. It is available on the CD in the back of this book.

Entering Code into the Repository

The first thing that you need to do with your source code is to enter it into the repository. To do so, load the source file that you want to enter, and then press C-x v i. This registers the file, which means that there is now a control file in the repository. After this is done, a string appears in the mode line. For RCS, this string is RCS:1.1. For CVS, it is CVS:1.1. For SCCS, it is simply SCCS.

After all your software is in the repository, several options become available. The first thing that you might notice is that all your source is now read-only. This protects you from modifying source at the filesystem level without first making sure that you are tracking your changes. To check a file out of the version control system, thereby locking the file, you use the same keystroke that is used to toggle the read-only buffer flag: C-x C-q. This sets a lock on the file, in addition to making a writable copy available. You can also use the key sequence C-x v v.

Now that you have access to your source file, you might want to add some headers to it. Version control headers allow RCS to put details into the source file, such as the version of the file or a change log. Emacs can automatically add headers for you if you are unsure what you want to add. Just put the cursor near the top header of your file and type C-x v h. The headers that are installed are dependent on the version control system that is in use.

Now it's time to decide if you like the changes you've made. To do so, you can use C-x v = to compare the current version with the last checked-in version. When the system command completes, the output of diff is displayed in a buffer named *vc-diff*. You can peruse this file at your leisure to determine if the changes you made are correct. If these changes are exceptionally complex, you can also use ediff to view the differences by choosing File with Revision from the Compare menu. See Hour 14, "Finding Differences Between Files," for details.

If you want to throw out the changes you've made, use C-x v u to revert to the last checked-in version. When you do this, everything that you've done since you last checked out the file is lost. If you want to keep your changes, use C-x C-q to toggle the read-only state again. Instead of making the toggle immediately, a new buffer, called *VC-log*, appears. After this buffer is up, you can enter comments that relate to the change you're about to make. If you can't remember all the changes that you made, you can use C-x v = again to bring back the difference buffer. Entering a good log is important. These commands, which can appear in the source code, are used to remind yourself--or others--about the changes you made.

If you have performed several check-ins already, you can use M-p and M-n to pull back log messages from previous check-ins. You can even use M-r and M-s to search forward or backward in the logs that you've previously entered to find just the right one. This makes it easy to check in multiple files with exactly the same log message. When you are done entering a log, press C-c C-c to commit your changes and save the log.

Even now, it is not too late to discard the changes you just made. The keystroke C-x v c cancels the last commitment that was made. It is usually unwise to cancel revisions, however, because the information is lost forever. Instead, just back the changes out and save under a new revision number. That way, it is always possible to get those changes back if they are needed in the future.

Querying the Repository

Now that you are familiar with the register, check-out, check-in cycle, it's time to learn about querying the repository. Everything that you might possibly want to know about the source code you've checked in can be found and displayed in Emacs. For example, the log message that was recently entered can be queried with C-x v l. This opens a *vc* buffer. In this log, you find information that is relevant to the system you are using, including the log messages.

The tool tinyrlog.el provides additional functionality to the log output. Download it from the CD-ROM and read its documentation for details.

You can also pull up old versions with C-x v ~. This prompts you for the version number that is to be referenced and saves it as file~version~. This enables you to make a patch against an old version of software--or accept patches on old versions of software--more easily. This is the same method that is used by the Compare File with Revision menu item.

When you are working on large software changes, sometimes it is difficult to keep track of the state of all the files. You can use Speedbar (introduced in Hour 18, "Editing C, C++, and Java Files"), which displays a * next to each file that is currently checked out. You can also get a directory listing that specifies all checked out files with C-x v d; at the prompt, enter the source directory or just press Enter. This listing is in dired mode, which is discussed in Hour 16, "Interfacing with the System." Unlike dired mode, there are special commands for performing batch operations. The character v is the version control prefix character, and the next character is the same as the one that is found under the C-x v.prefix for files.

In a dired listing, the command v= generates a difference of the last check-in version, and vl generates a log. The command vv performs the next action that is appropriate for a file, such as beginning the check-in process. Each of these commands operates on the current file, or on all files that are marked using the m key. The g command refreshes the status of all the files that are committed in the repository, and the special mark command *l marks all the files that are locked by the user.

Therefore, while you are in VC-controlled dired mode, the sequence * l v v enables you to check in all the files that are currently locked. This makes it even easier to check in several files that all have the same comment. Other operations, such as such as reverting, work similarly against all marked files.

Eventually, it will be important to release the software. When this occurs, it is time to make a snapshot. You can make a snapshot directly from Emacs with C-x v s, which asks you for a name for your snapshot. This performs different actions, depending on the revision control software that you are using. In general, it tracks the name that you enter with a version number from each file. It is important when you do this to remember exactly which files went into the software release on which you are working.

If you make revisions after taking a snapshot, you can always get that snapshot back by retrieving it with C-x v r. After you have retrieved the snapshot, you can make branches and patches in your repository, easing your capability to service software that has been released.

If you are writing software that follows the GNU conventions of including a ChangeLog file, you can use Emacs to update a change log. A ChangeLog is a file that specifies changes made to the source code, and the times at which they were made. Using the command C-x v a.causes Emacs to reference the repository log and generate the change log automatically. This can be a big time saver for authors of free software.

Sams Teach Yourself Emacs in 24 Hours		ContentsIndex
Hour 19: Programming Utilities		Previous HourNext Hour
Sections in this Hour: Version Control Systems Summary Compiling Programs Q&A Debugging Programs Exercises		Previous SectionNext Section

© Copyright Macmillan USA. All rights reserved.