Learning GNU Emacs, Third 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.

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 to the version number that matches the file you downloaded), and you will see a list of files.

$ 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.^[1] You should see quite a bit of output that shows what parts of the system the build script is looking for.

   ^[1] Depending on your system and its permissions, you may have to switch to the root user using su to install Emacs. In that case, you won't need to preface the final make command with sudo.

   $ ./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,^[2] you're in good shape, so go ahead and install it:

   ^[2] One of the authors was not able to see the splash screen, but the install worked fine nonetheless. We say forge ahead even if you don't see 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!