Learning GNU Emacs, 3rd Edition

Emacs was originally built on a Unix system and continues to run on the multitude of Unix variants out there. We're going to download the latest source and show you how to build Emacs from scratch. It's not really that hard and it has the salutary effect of keeping you up-to-date with future releases.

13.1.1 Where to Get Emacs?

If you can't wait, the primary source for downloading Emacs is http://ftp.gnu.org/pub/gnu/emacs/. Alternatively, you can use CVS to nab the absolute latest build. But more on that in a minute.

13.1.1.1 Downloading Emacs from the Web

You can get Emacs from any one of many sites—as long as your Internet connection is fast enough to transfer a 20 MB file easily. You must also have at least 120 MB of disk space free; this number will certainly grow in future Emacs releases.

The Free Software Foundation maintains a definitive list of all mirror sites. The FSF is the principal sponsor of the GNU Project and it is housed at their site. If you want to look around a bit, http://www.gnu.org/ is the place to start. Or as mentioned earlier, you can just jump directly to the directly listing for Emacs at http://ftp.gnu.org/pub/gnu/emacs/. You should see a list similar to Figure 13-1.

Figure 13-1. The emacs directory at gnu.org

Look for the latest version of Emacs (21.3 in Figure 13-1) and download it.

13.1.2 Where to Put Emacs?

Regardless of where you go to get the source, where you put the files you download is really up to you. For our Unix-based systems, we downloaded everything into /usr/local/install. This is a fine place to start, but if you have a favorite download/development area, feel free to use that. In fact, you can even put everything in your home directory while you're building things.

The only thing to remember is that the build process involves a lot of files that you won't need after everything's done. Make sure you put things somewhere that's easy to clean up when all is said and done.

As for the final destination of the executable, that's also up to you. Most Unix systems (including Mac OS X) will do well to use the /usr/local hierarchy. That directory is both common and the default choice in the build scripts. If you're not on a machine that you have complete control over, though, you can certainly install Emacs into your home directory (or a subdirectory you keep for you own software).

One quick note on using your home directory for the executable version of Emacs: it does make it easy to back up Emacs or transfer it to another machine if you upgrade your system (we know from experience!). However, it can limit who has access to Emacs. If another user works on the same machine and you both want to use Emacs, installing to a common directory (like /usr/local ) is definitely the way to go.

13.1.3 Uncompressing and Unpacking

Now that you have the file, you need to do two things to it before you can actually build Emacs: uncompress and unpack. You can use the tar command to do both. Make sure you are in the directory where you downloaded the Emacs file. Type the following command (changing the

n

$ tar xvzf emacs-21.n .tar.gz

x emacs-21.3, 0 bytes, 0 tape blocks

x emacs-21.3/AUTHORS, 77854 bytes, 153 tape blocks

x emacs-21.3/FTP, 8950 bytes, 18 tape blocks

x emacs-21.3/INSTALL, 42841 bytes, 84 tape blocks

x emacs-21.3/README, 4046 bytes, 8 tape blocks

x emacs-21.3/BUGS, 1042 bytes, 3 tape blocks

x emacs-21.3/move-if-change, 129 bytes, 1 tape blocks

x emacs-21.3/ChangeLog, 161418 bytes, 316 tape blocks

x emacs-21.3/Makefile.in, 25461 bytes, 50 tape blocks

. . .

This list of created files goes on for quite a while—over 2500 files for Emacs 21.3. If you don't want to see the list, omit the v (verbose option) from the tar command. When this command completes, you have all of the files for Emacs.

Now that any necessary preparations are out of the way, you can go through the steps to build and install Emacs itself.

13.1.4 Downloading Emacs from CVS

As we mentioned earlier, you can also use CVS to pull the source files. The big advantage with CVS is that you get the absolute latest version.

1. Create or switch to a directory where your Emacs build can remain. Don't do this in a temporary directory unless you don't plan on keeping Emacs around. Once there, set up the CVS_RSH environment variable:

% setenv CVS_RSH ssh

2. If the setenv command is not recognized, you're probably running bash instead of a csh-derived shell. In that case, use the following command for the environment variable.

$ export CVS_RSH="ssh"

3. Use the cvs command to grab the source code.

% cvs -z3 -d:ext:anoncvs@savannah.gnu.org:/cvsroot/emacs co emacs

The authenticity of host 'savannah.gnu.org (199.232.41.3)' can't be established.

RSA key fingerprint is 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.

Are you sure you want to continue connecting (yes/no)?

4. Verify that the public key matches this key:

80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5

5. That just makes sure you actually got connected to the right system and aren't being fed some malicious alternative.

6. If the keys match, type yes and press Enter.

Warning: Permanently added 'savannah.gnu.org,199.232.41.3'

(RSA) to the list of known hosts.

cvs server: Updating emacs

U emacs/.cvsignore

U emacs/AUTHORS

U emacs/BUGS

U emacs/COPYING

U emacs/ChangeLog

U emacs/FTP

U emacs/INSTALL

...

You'll see thousands of filenames flying by. If you have a slow network connection, this process could take a while. Hang in there, though—you're on your way to building the absolute latest version of Emacs!

13.1.5 Building Emacs

Unless you get a prebuilt version of Emacs that is right for your system, you will need to build and install the many executable components of Emacs from source code before you can use it. At this point, it doesn't matter how you got the source code (HTTP or CVS), you just need to compile it! Here is some information to get you started on this task.

Your source code has a top-level directory with a name like emacs-21.3. In this directory, you will find files called INSTALL and README. Examine README first; it contains useful general information as well as last-minute release notes that may be important for you to read before proceeding. Then read INSTALL, which gives step-by-step instructions for building Emacs. Even if you aren't a Unix expert, you should be able to follow these instructions. (For convenience, we provide a procedure you can follow later in this section.)

The FSF's standard installation procedure gets more comprehensive and bulletproof all the time. Still, the actual ease of building Emacs depends primarily on what combination of hardware and software you have. The FSF's installation script includes a program called configure that examines your system, figures out what hardware and software you are running, and configures Emacs accordingly.

configure is likely to guess correctly if you have a popular combination (such as a Sun SPARC CPU and a recent release of Solaris). If this is true, you should be able to build Emacs without lots of tweaking or technical expertise. However, if you have an unusual setup—a wildly obsolete computer or operating system version, an unusual hardware/software combination, or unconventional system configuration—then you will have no choice but to tweak the software. That's beyond the scope of this book, but those README and INSTALL files that come with the source distribution are a great place to start when dealing with uncommon setups.

Here's a procedure for building Emacs that you can use as a guide:

1. Change to the directory where you uncompressed and unpacked Emacs. For example, if you placed it in the /usr/local/install directory:

$ cd /usr/local/install/emacs-21.3

2. Run the configure utility.[88] You should see quite a bit of output that shows what parts of the system the build script is looking for.

$ ./configure

creating cache ./config.cache

checking host system type... sparc-sun-solaris2.9

checking for gcc... gcc

checking whether the C compiler (gcc ) works... yes

checking whether the C compiler (gcc ) is a cross-compiler... no

checking whether we are using GNU C... yes

checking whether gcc accepts -g... yes

checking whether ln -s works... yes

checking how to run the C preprocessor... gcc -E

3. If configure is successful, you should see a handy summary message similar to the following:

Configured for `sparc-sun-solaris2.9'.

 Where should the build process find the source code? /usr/local/install/emacs-21.3

 What operating system and machine description files should Emacs use?

    `s/sol2-5.h' and `m/sparc.h'

 What compiler should emacs be built with?        gcc -g -O2

 Should Emacs use the GNU version of malloc?       yes

 Should Emacs use a relocating allocator for buffers?  yes

 Should Emacs use mmap(2) for buffer allocation?     no

 What window system should Emacs use?          x11

 What toolkit should Emacs use?             LUCID

 Where do we find X Windows header files?        Standard dirs

 Where do we find X Windows libraries?          Standard dirs

 Does Emacs use -lXaw3d?                 no

 Does Emacs use -lXpm?                  yes

 Does Emacs use -ljpeg?                 no

 Does Emacs use -ltiff?                 no

 Does Emacs use -lungif?                 no

 Does Emacs use -lpng?                  no

 Does Emacs use X toolkit scroll bars?          no

If the configuration process fails for any reason, you'll want to go back and consult the INSTALL document. It has several tips and tricks for particular systems and situations.

4. If everything is properly configured, you can go ahead and compile Emacs with the make utility. This may take a while, so start it before you head out for lunch.

$ make

if [ ! -f /usr/local/install/emacs-21.3/lisp/abbrev.elc ]; then \

 make bootstrap; \

fi

cd lib-src; make all \

 CC='gcc' CFLAGS='-g -O2' CPPFLAGS='' \

 LDFLAGS='' MAKE='make'

gcc -DHAVE_CONFIG_H -I. -I../src -I/usr/local/install/emacs-21.3/lib-src

-I/usr/local/install/emacs-21.3/lib-src/../src -g -O2 -o test-distrib

/usr/local/install/emacs-21.3/lib-src/test-distrib.c

./test-distrib /usr/local/install/emacs-21.3/lib-src/testfile

gcc -DHAVE_CONFIG_H -I. -I../src -I/usr/local/install/emacs-21.3/lib-src

-I/usr/local/install/emacs-21.3/lib-src/../src -g -O2 /usr/local/install/

emacs-21.3/lib-src/make-docfile.c -lsocket -lnsl -lkstat -o make-docfile

...

5. When that completes, the INSTALL document recommends testing your newly built Emacs with the following command:

$ src/emacs -q

Emacs should run and you should get an introduction screen similar to Figure 13-2.

Figure 13-2. Emacs test after building on a Linux system

6. If you see the Emacs splash screen,[89] you're in good shape, so go ahead and install it:

$ sudo make install

or, if you su'd to root earlier, simply:

$ make install

You'll be prompted for your password. After the install completes, you should be all set to use Emacs. Congratulations!

As you may have picked up reading other parts of this book, we treat Mac OS X as a Unix variant for many tasks. We do that with good reason, of course. Mac OS X is based on Unix. For example, you could more or less follow the CVS and Unix build instructions in the previous sections and come away with a full installation of Emacs.[90] However, as you know, Mac OS X can be a little different in some ways; it doesn't have all the Unix utilities by default (see the section on installing Ispell for one example of this). This section covers installing Emacs on Mac OS X as well as other issues such as running Emacs from the command line, changing the location of your Meta key, and installing Ispell. And if you do want to build Emacs from scratch using CVS, we have a few notes on that, too.

13.2.1 "But I Already Have Emacs"

Mac OS X comes with a version of Emacs installed: 21.2.1 with Panther (10.3.2) and 21.1.1 with Jaguar (10.2.8). To start this version, use the Terminal application in your Utilities folder (which is inside the Applications folder) and just type emacs.

Figure 13-3 shows the built-in Emacs running in the Terminal application.

Figure 13-3. The Terminal-based Emacs built into Mac OS X

But you should be aware that although it is built-in and certainly the easiest to start using, this version of Emacs has a few shortcomings:

1. It runs, well, you know, in a Terminal.

2. It does not have any of the graphical user interface features such as icons or expected mouse behavior.

3. The Terminal application often supersedes Emacs when handling things like the scrollbars and some key bindings.

If you can live with those restrictions—or have no choice—then feel free to skip the next section on installing Emacs and get on with using the version you have. The vast majority of information in this book still applies.

13.2.2 Installing Prebuilt Emacs on Mac OS X

13.2.2.1 Downloading Alex Rice's application bundle of Emacs 21.3.5

Most Mac users will want to grab a prebuilt binary version of Emacs that's all ready to go. Alex Rice created just such a build. It can be found online (for free![91]) at: http://mindlube.com/products/emacs/index.html. You can download directly from that page, but be sure to grab the correct version. You can pick from the Jaguar (Mac OS X 10.2) version or the Panther (Mac OS X 10.3) version.

You'll be downloading a .dmg file which is the Mac disk image format. It should automatically unpack and mount itself, but if it doesn't for some reason, just double-click on the .dmg file after it is completely downloaded.

As it launches, you'll need to read and agree to the license. After you do that, you should have a new "disk" mounted and you'll see the Emacs application all ready to drag and drop. (See Figure 13-4.)

Figure 13-4. The mounted disk image for Emacs on Mac OS X (Panther)

Drag the big gnu to your Applications folder and off you go. That really is all there is to it. Many, many thanks to Alex Rice and Mindlube! (And feel free to eject the mounted image once you have copied Emacs to your hard drive.)

13.2.3 Building Emacs from Source on Mac OS X

% tar xvzf texinfo-4.7.tar.gz

% tar xvf texinfo-4.7.tar

% ./configure

% make

% sudo make install

13.2.4 Starting Emacs from the Command Line on Mac OS X

On Mac OS X, you have Emacs preinstalled, but as we know, it is an older version of Emacs. Let's say that you have installed the graphical version and want to start it with some command-line arguments. For example, you might want to run emacs —debug-init to debug your .emacs file. The Mac OS X Gnu icon certainly should be a permanent fixture on your Dock, but at times the command line is the way to go.

We learned this trick from Andrew Choi's Mac OS X FAQ, and we share it here, slightly tweaked, for convenience. Check out his page at http://members.shaw.ca/akochoi-emacs/stories/faq.html.

Essentially, you replace the binary that comes with Mac OS X with a shell script that runs the new version of Emacs you installed. You might want to simply rename the old binary so that you can on occasion use it instead.

Here's the procedure.

1. To be sure which Emacs runs when you type emacs, type which emacs in the Terminal application.

% which emacs

/usr/bin/emacs

2. Rename or delete /usr/bin/emacs.

% sudo mv /usr/bin/emacs /usr/bin/oldemacs

3. You'll be prompted for your password.

4. Create a file called emacs with the following two lines:

#!/bin/sh

/Applications/Emacs.app/Contents/MacOS/Emacs "$@"

If you installed Emacs into a different folder, adjust the second line accordingly.

5. Move the file you created to /usr/bin:

% sudo mv emacs /usr/bin

6. Change /usr/bin/emacs to be executable by the world:

% chmod +x /usr/bin/emacs

Now you can invoke graphical Emacs from the terminal window simply by typing emacs, with or without command-line arguments.[92]

13.2.5 Mac OS X and the Meta Key

This book has mentioned using the Command key for Meta on Mac OS X. By default, the Command key (sometimes called the Open Apple key, or more simply xxxMacSymxxx) is Meta. But in fact you have a choice. The variable mac-command-key-is-meta can be used to select which key you want to use.

As the variable name implies, setting mac-command-key-is-meta to t means that you use xxxMacSymxxx as the Meta key. So you can type the M-x combination as xxxMacSymxxxx.

The alternative (setting mac-command-key-is-meta to nil) sets the Option (or Alt) key to be your Meta key. You might do this if you want to continue using the Command key for Mac functions or if you find that Option is simply easier to reach. Of course, it's not quite that simple. Emacs still traps the Command key. That trapping is supposed to be turned off with one more variable: mac-pass-command-to-system, but to be honest, we never got that to work.

13.2.6 Installing Ispell

As mentioned in Chapter 3, Emacs uses Ispell for its spell-checking functionality. However, despite voluminous hooks to it, the Ispell executable is not part of Emacs and is not installed by default on Mac OS X. You must therefore install Ispell to get spell-checking to work properly.

We took the easy path to doing this: downloading and installing Fink (see http://fink.sourceforge.net for instructions). Fink is an all-purpose Mac OS X installer that enables you to install Unix software on your Mac easily.

After installing Fink, installing Ispell was completely painless:

% fink install ispell

Just one further step is required so that Emacs finds Ispell without tweaking. Create a symbolic link between the location where Fink installs Ispell (/sw/bin/ispell) and where Emacs expects Ispell to be (/usr/bin/ispell).[93]

% sudo ln -s /sw/bin/ispell /usr/bin/ispell

Voilà. Emacs spell-checking with Ispell now works as described in Chapter 3.

You can also download and install Emacs 21.3 for the various Windows platforms (Win95, Win98, Win2K, WinXP, and so on). As most Windows machines do not ship with the tools required to build Emacs from scratch, we'll look at downloading and installing prebuilt executables.[94]

13.3.1 Installing Emacs

13.3.2 Where to Put Your .emacs File

Probably the single biggest Windows consideration is the location of the .emacs file. This file goes in your "home" directory. We use quotes there because the Windows world doesn't have a strictly defined home directory the way some other operating systems like Unix and Mac OS X do. By default, Emacs assumes that the C:\ folder is your home directory. You can put your .emacs file there, but you can also modify your home directory using the Windows environment variable called HOME. To change this environment variable on Windows XP, select System from the Control Panel. A System Properties window displays. Choose the Advanced tab, then choose Environment Variables. HOME is probably not listed; click on New, then type HOME and the path to your desired home directory. Emacs will now look for the .emacs file in this directory.

Because of naming compatibility issues, older Windows versions of Emacs used the _emacs file rather than the .emacs file for customization and configuration. This file is still a valid option. However, if both _emacs and .emacs are found in the home directory, only .emacs is used.

13.3.3 Starting Emacs from the Command Line

The Emacs bin folder includes two related files, each sporting a Gnu icon: emacs.exe and runemacs.exe. Typically you'll use runemacs.exe; this runs Emacs graphically without opening a console window. The other file, emacs.exe, can be used to run Emacs from the command line as described next.

To run Emacs from the command line, cd to the directory where you installed Emacs and type emacs -nw (or whatever command-line argument you wanted to use; -nw runs Emacs in the console window). You can also do this by choosing Start → Run, then selecting Browse to locate emacs.exe. Add any command-line arguments you wish, and then click OK to invoke Emacs using these arguments.

13.3.4 Making Emacs Act like Windows: CUA Mode

CUA stands for common user access, a standard originally developed by IBM. CUA mandates that certain keys should always perform certain functions. In Windows, for example, C-c copies and C-v pastes from one application to another. As you know, Emacs uses these key bindings for its own purposes.

That's where Kim Storm's CUA mode comes in. This mode was so popular that it is now part of Emacs.[95] It allows standard Windows key bindings, like C-x for cut and C-v for paste, to work properly within Emacs. It's quite clever—these keys cut and paste only when an active selection exists. That leaves the normal functionality of multistroke commands like C-c C-f in fine shape.

To turn on CUA mode, select C-x/C-c/C-v cut-and-paste (CUA) from the Options menu. If you decide you want to use CUA mode for multiple sessions, select Save Options to have Custom (discussed in Chapter 10) automatically add it to your .emacs file.

As you can see from the option name, in this mode, C-x is used for cutting text, C-c is used for copying text, and C-v is used for pasting text. What is not so apparent is that C-z runs undo rather than minimizing the window (in CUA mode, you can minimize using C-x C-z).

What if you're used to confirming a region before you cut it using C-x C-x? You can type C-c C-x C-x in this case. This works in part because C-c cancels the active region. Remember that C-x would normally cut.

Strictly speaking, C-x C-x doesn't immediately cut text, if you type it fast enough. Cut is really bound to C-x . In other words, Emacs is watching to see if you type something else really quickly. If you have a region highlighted and type C-x C-s to save the buffer, Emacs does the right thing. But if you pause after C-x, you'll cut text. This is true of C-c as well. If you immediately type another sequence after C-c, Emacs uses C-c as a prefix. If you pause, it copies the highlighted text.

CUA mode has a few other interesting behaviors. It has highly advanced rectangle support. (Rectangle editing is described in Chapter 7.) It also has the common behavior of replacing highlighted text. If you select a region and start typing, the highlighted text is replaced. Taking this one step further, you can do a quick and dirty search and replace in this way. Let's say that the text you typed over is just the first of several identical instances where you want to replace text. Typing M-v (for cua-repeat-replace-region) replaces the next instance. Repeat this command to continue making replacements. If there is no string to replace, M-v does nothing.

For example, let's take our classic Dickens passage and replace the word times with rhymes:

Highlight the word times.

The word times is highlighted.

Type: rhymes

Emacs replaces times with rhymes.

Type: M-v

Emacs replaces the next instance of times with rhymes.

You may love CUA mode or you may hate it; the only way to see if your fingers are ready for this option is to try it out. If you've used Emacs for years, you may find CUA mode keeps doing unexpected things. Your finger habits are set to Emacs's ways. On the other hand, it's hard to move back and forth between applications and change your finger habits all the time. If you have not yet gotten used to the Emacs key bindings, you may well love CUA mode, as many people do.

Table 13-1 lists CUA mode commands.

Table 13-1. CUA mode commands

13.3.5 Installing Ispell

Installing Ispell on Windows can be tricky. Emacs 20 and beyond includes features like Flyspell and earlier versions of Ispell won't handle that functionality. Many Windows users do not compile their own software, and even if they did, the very newest Ispell also doesn't work with Emacs.

We found the version we describe here in a post by Raymond Zeitler (http://lists.nongnu.org/archive/html/help-emacs-windows/2004-06/msg00023.html), and we thank him heartily for it. The only downside to this version is that it is designed for English speakers. It may well work with other languages, but you'd have to find the .hash file appropriate for your language.

The first step is to download a Windows binary of Ispell 3.1.20.[96]

Open a command window. On Windows XP, you open it using Start → Run, then typing command and clicking OK.

Create a temporary directory and move there (you can substitute another name for tmp).

C:\> mkdir tmp

C:\> cd tmp

FTP to gatekeeper.dec.com.

C:\tmp> ftp gatekeeper.dec.com

Type anonymous as your username and your email address as your password.

Move to the /pub/GNU/windows/emacs/contrib directory.

C:\tmp> cd /pub/GNU/windows/emacs/contrib

Type bin to change to binary mode.

C:\tmp> bin

Download ispell.zip.

C:\tmp> get ispell.zip

Type bye to close your ftp session, then exit to close the MS-DOS window.

Unzip the archive with WinZip or Windows' own decompression utility. We need to move a few files around to make Ispell work properly with Emacs.

Move ispell.exe to Emacs' bin folder. For example, if you called the folder where you installed Emacs nqmacs, you would place the file in nqmacs\bin.

Move english.hash to your home directory (either C: or the one you defined earlier as the location for your .emacs file). Now copy english.hash to american.hash (both files must exist for Ispell to work properly). We suspect but cannot verify that this would not be necessary for users of systems expecting British English dictionaries.

There's a lot more to the world of Emacs in Windows. We encourage you to check out the frequently asked questions and documentation available online at http://www.gnu.org/software/emacs/windows/.