# Building Emacs
on MS Windows

On this page:

- Building Emacs on MS Windows
- Getting the Tools
- - A File Archiver
  - Tools for Building Emacs
  - - Avoid Problems: Check Your Setup
    - A Useful Tool: tee.exe
    - GNU Make: make.exe
    - GNU Makeinfo: makeinfo.exe
    - Some Smaller GNU Unix Utilities
    - GNU C compiler: gcc.exe
  - Tools to Get the Latest Emacs Sources
  - - GNU Command Line CVS: cvs.exe
    - SSH Helper for cvs.exe: Putty
- Getting Emacs Source
- - How to Download a Copy of Emacs CVS
- How to Build Emacs
- - How to Get Images Support (Optional)
  - - A guide for images support
  - Making it easy: A Script File for Building
- Installing the New Emacs
- Running Several Versions of Emacs
- Updating from CVS
- Exchanging Changes - patch.exe
- - Patches for the Emacs+EmacsW32 distribution

It is not much more difficult to build Emacs on MS Windows than on other OS:es. However what is harder is to get and setup the tools you need. There are some traps when doing this! And if you want to get the latest developing version of Emacs you need even more tools to be able to access the CVS repository where it is. You can also get a bit confused about what documentation to read, since the main documentation is for "unix like" OS:es. I will try to give some short advices about both this issues below.

The list below of programs needed to build Emacs should be sufficient. All the programs mentioned are also needed in this solution. It is however of course not the only solution, other programs can be used too.

Please also have a look at Unix Utilities for Emacs on MS Windows.

# Getting the Tools

## A File Archiver

Many tools are distributed in .tar.gz format or .zip format. You can use some commercial file archivers to handle those archives. Here is a nice GNU LGPL archiver that can do that too: http://www.7-zip.org/

## Tools for Building Emacs

### Avoid Problems: Check Your Setup

Do you already have everything needed? Are versions correct? Are there bad mixing of tools? You can easily run a first check of this with emacs-w32-build-check.pl that comes with EmacsW32. To do this you however need another program, namely perl from http://www.activestate.com/. (This little tool is perhaps not very complete, but it may keep you on the track.)

#### Tools in Your Path

There are some programs that need to be in your path when building Emacs from the sources in the CVS repository. These are the make programs, the compiler and some unix like utilities used in the build process.

#### Don't Mix!

Some of the tools, like sh.exe and make.exe, may be very hardly tighed together and it is in those cases important not to mix them. You must for example use MSYS make.exe if you use MSYS sh.exe. (But you can currently not use MSYS at all for some parts of the building process, see below.) The checking tool I mention above tries to see if they are.

Here is an example of what can happen if you mix MSYS make.exe with cmd.exe. Suppose MSYS make.exe is the one used and you try to avoid using MSYS sh.exe by using SHELL=cmd.exe as a parameter to make. This will just hang. And it hangs very hard. It can be very hard to find out what is happening in such cases.

#### Why You Should Avoid MSYS

I believe MSYS tools does most of the build process fine, but unfortunately it fails at some small points. And that makes it currently pretty useless for the purpose of building Emacs. An example of the problem is when the build process should update the autoloads. With MSYS the following happens:

    [Please ignore a syntax error on the next line - it is intentional]
    /bin/sh.exe: -c: line 1: unexpected EOF while looking for matching `""'
    /bin/sh.exe: -c: line 2: syntax error: unexpected end of file

    Directories: calc calendar emacs-lisp emulation eshell gnus
      international language mail mh-e net obsolete play progmodes term
      textmodes toolbar url

    ../bin/emacs.exe -batch --no-init-file --no-site-file --multibyte \
            -l autoload \
    	--eval '(setq find-file-hook nil \
    		find-file-suppress-same-file-warnings t \
    		generated-autoload-file \
    		  "/c/emacscvs/emacs/lisp/loaddefs.el")' \
    	-f batch-update-autoloads /c/emacscvs/emacs/lisp calc calendar \
               emacs-lisp emulation eshell gnus international language \
               mail mh-e net obsolete play progmodes term textmodes toolbar url
    Opening output file: no such file or directory,
      c:/c/emacscvs/emacs/lisp/loaddefs.el

As you can see above an MSYS format file name was inserted by MSYS make into the --eval parameter to Emacs. Emacs do not understand this file format and the command therefore fails.

I believe the best cure for this problem would be to rewrite those pieces of the Makefiles where this occurs. But that has not yet been done.

Below are some more problems I have currently seen when using MSYS to build Emacs:

- Addpm.exe fails because it is called with "addpm /q" by make install. MSYS sh believes /q is a path and changes it to \q. Addpm.exe then think \q is a path and adds this to the registry. Fix: Just rerun addpm.exe from cmd.exe to fix it. A better solution would be that addpm.exe used -q instead (for quiet).
- Building some part of Emacs (for example Info) fails. This is because MSYS sh can not run .bat-files correctly (it treates them as sh scripts!?). Several bat files are used in the build process.
- makeinfo from MSYS does not handle CR-LF correctly and can't be used (without problem).

### A Useful Tool: tee.exe

The program tee.exe is very good to have if you want log files when building. See below for an explaning example. You can find tee.exe in the CoreUtils package from http://gnuwin32.sourceforge.net/.

### GNU Make: make.exe

GNU Make is the utility that runs the Emacs building process (which is very complex). On http://www.mingw.org/ go to the Download page where you can find a file with a name that looks like mingw32-make-3.80.0-3.exe. This is an installation package containing GNU Make documentation and mingw32-make.exe. Rename this file to make.exe and put it in your path.

### GNU Makeinfo: makeinfo.exe

GNU Makeinfo is used to build Emacs documentation. On http://gnuwin32.sourceforge.net/ download the package TexInfo, which contains the file makeinfo.exe. Put this in your path.

### Some Smaller GNU Unix Utilities

During the build some programs common on different unix dialects are used. Some of these you can find in CoreUtils that you can download from http://gnuwin32.sourceforge.net/. You need to put cp.exe, mv.exe, rm.exe and touch.exe in your path.

A warning: There are numerous port of these unix programs to MS Windows. All of them does not work. I know that by timewasting experience. The GNU ports above does work as they should.

The unix style program find.exe and its relative xargs.exe are also used during the build. You can find these in FindUtils from http://gnuwin32.sourceforge.net/. These must be in your path.

### GNU C compiler: gcc.exe

Emacs C sources can be compiled with the free GNU C/C++ compiler. You can find a port to MS Windows of this here: http://www.mingw.org/. A file named something like MinGW-3.1.0-1.exe is what you want. It is an installation package. (Currently this file is missing in the "Current" section, see this message

The MinGW bin directory must be in your path.

## Tools to Get the Latest Emacs Sources

If you want to get latest Emacs sources from Emacs CVS then you need something like the tools below.

### GNU Command Line CVS: cvs.exe

On this page http://www.cvsnt.org/ you can download a command line cvs.exe client. (It is included in the CVS server and client download (though the installer currently does not tell you this).

### SSH Helper for cvs.exe: Putty

*Note*: I earlier wrote: The latest version of the CVSNT client has built in SSH protocol so you do not need plink and can skip this section! Unfortunately this does not seem to work yet (2005-11-24).

Cvs.exe must have a program that helps it with SSH access. The file plink.exe from SSH client Putty can do this. You also need putty.exe. Putty's home page is here: http://www.chiark.greenend.org.uk/~sgtatham/putty/

There are two things you must do before cvs.exe will work with plink.exe:

1. Set the environment variable CVS_RSH: set CVS_RSH=full_path_to_plink.exe
2. Run putty.exe once to save the CVS repository server's host key:
   1. Start putty.exe.
   2. In the Host Name field enter the name for Emacs CVS repository host (see below).
   3. Click Open.
   4. "Putty Security Alert" will pop up. Click Yes to save the host key.

# Getting Emacs Source

There are two main ways to get the source. You can either download a source tarball or get it from the develop repository, usually called CVS (after the software used for taking care of it). A source tarball is just a package file with the sources. Such packages are available for the release version and at some point in the developing fo Emacs. If you go to Emacs home page you will find more information about where to find tarballs and CVS.

## How to Download a Copy of Emacs CVS

If you want to build from CVS you must first download a copy of Emacs from the CVS repository you can use cvs.exe:

cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/sources/emacs co emacs

This will give you a copy of the CVS repository in the subdirectory "emacs" below your current working directory. You can use exactly the same command to update your copy later.

Notice: You must run the command cvs update -kb in the emacs\nt subdirectory. (Ready more about this in emacs\nt\INSTALL.)

# How to Build Emacs

In principle you should now only have to start reading INSTALL in the "emacs" subdirectory and follow the instructions there. However this is currently not the right place to start reading. Instead read emacs\nt\INSTALL. This file is specific to MS Windows. You will also want to read emacs\INSTALL.CVS and maybe later emacs\INSTALL.

Unfortunately some of the instructions there are yet not quite correct. To make it simple you may follow these instructions instead:

Use tee.exe!
  Using tee.exe is not necessary but it may help you finding problems. With tee.exe you can both have the output send to the screen and to a log file at the same time. Use it like this:

  make bootstrap 2>&1 | tee -a my.log

  That will append all output to my.log and you can still see what is going on on the display.
Run all commands from the "emacs\nt" subdir
  You can not run make from the "emacs" subdirectory on MS Windows. Instead it must be done from the "emacs\nt" subdirectory. So first change your working directory to "emacs\nt".

  Later you may run some commands from for example the "emacs\lisp" subdirectory. (INSTALL.CVS tells you to do this in some cases.)

Step 1: Run "configure.bat"
  See emacs\nt\INSTALL for more info.
Step 2: Run "make bootstrap" to build Emacs
  See emacs\INSTALL.CVS for more info.
Step 3: Run "make info" to build the Info manual
  emacs\INSTALL does not tell you that you have to "make info" to build the Info pages. You should do this before you run "make install".

## How to Get Images Support (Optional)

You do not need image support to build Emacs. However it could be fun and I found this excellent guide for how to get image support when compiling Emacs on emacswiki.org. I shamelessly stole it and put it here so that you can have it at hand if you use this guide for building Emacs. I can not even give credit to the author, since she/he has preferred to be anonymous.

Note that you have to do two things to get image support:

- Run configure.bat with image support headers available.
- Have the image dll-files where Emacs can find them when you start Emacs.

According to nt\INSTALL you may put the image library files either on your path or in Emacs bin dir. Having them in the path is perhaps easier if you are testing several builds.

The author of the guide has downloaded the zip files for the image libraries. I myself prefer to use the Setup-versions. They are nicely made and very easy and fast to install.

### A guide for images support

Several images library is necessory for images support in Emacs. All of them can be downloaded at http://gnuwin32.sf.net. Both the bin packages(for .dll files) and the lib or src packages(for .h files) should be downloaded first. Files of .dll is for runtime, and .h for compiling.

- JPEG support
  - Required files: jpeg62.dll, jconfig.h (in bin & lib packages)
  - Current: jpeg-6b-4-bin.zip, jpeg-6b-4-lib.zip
- GIF support
  - Required files: libungif.dll, gif_lib.h (in bin & src packages)
  - Current: libungif-4.1.0b1-bin.zip, libungif-4.1.0b1-src.zip
- TIFF support
  - Required files: libtiff3.dll, tiffio.h, tiff.h, tiffvers.h (in bin & lib packages)
  - Current: tiff-3.7.2-bin.zip, tiff-3.7.2-lib.zip
- XPM support
  - Required files: xpm4.dll, X11/xpm.h, simx.h (in bin & lib & src packages)
  - Current: xpm-3.5.1-1-bin.zip, xpm-3.5.1-1-lib.zip, xpm-3.5.1-1-src.zip
- PNG support
  - Required files: libpng13.dll, png.h, pngconf.h (in bin & lib packages)
  - Current: libpng-1.2.8-bin.zip, libpng-1.2.8-lib.zip
- Zlib (required by PNG)
  - Required files: zlib1.dll (in bin packages)
  - Current: zlib-1.2.2-bin.zip

Assuming all required .h files are in C:\free_ware\gnuwin32\include. Run cmd.exe, then to cvs-emacs\nt directory:

          emacs\nt> configure.bat -h
          emacs\nt> configure.bat --with-gcc --cflags -IC:/free_ware/gnuwin32/include
          emacs\nt> dos2unix makefile

Copy all .dll files to the directory EMACS_INSTALL_DIR\bin, so this Emacs will support images.

## Making it easy: A Script File for Building

In the download area for EmacsW32 there is a script file called make-cvs.cmd that can do the building automatically. You have to edit it a little bit to reflect your paths and you need some supporting files that you find in the same place.

# Installing the New Emacs

Step 4: Run "make install" to get everything in place
  See emacs\nt\INSTALL for more info.
Step 5: Run EmacsW32 Install Wizard
  At this point "emacs\nt\INSTALL" leaves you on your own. The installation is however not quite ready yet. There are really no useful shortcuts for starting Emacs in Explorer and there is either no good way to open a new file for editing from the windows command line. Maybe you also miss file extension associations to Emacs?

  The main missing pieces are shortcuts and command line support to open files with Emacs. I suggest that you use EmacsW32 Install Wizard to get the shortcuts and command line support in place. It also give you the possibility to do some tweaking of Emacs that may make it more easy for You as an MS Windows user to use it.

# Running Several Versions of Emacs

If you use EmacsW32 it is quite easy to switch between different versions of Emacs. You just run the file usethis.exe in the bin directory of the version you want to use. This will tell emacsclient.exe to use this version. (And emacsclient.exe is used by all the shortcuts for emacs and by the emacs.cmd file.)

Since some custom options are different in different versions of Emacs you may also want to enter something like this in your .emacs:

          (cond
            ((equal emacs-version "21.3.1")
              (setq custom-file "~/.emacs-cust-21.3.el"))
            (t
              (setq custom-file "~/.emacs-cust-cvs.el")))
          (load custom-file)

# Updating from CVS

You can update from CVS exactly the same way as you downloaded your first copy.

Step 6-... : After CVS updates
  Read what emacs\INSTALL.CVS says about this. But use EMACS=../src/oo-spd/i386/emacs instead when it says EMACS=../src/emacs.

# Exchanging Changes - patch.exe

There is a simple way to handle changes to the source code. This allows you to send the changes to other people. They can add your changes easily and later remove them. If the changes are in multiple files it is not more to do than if it were in a single file. A very powerful system!

I did not know about this and I therefore wrote in a mail conversation Because I still have not really understood how to use diff files. What will you do with them? I got this very useful answer from Juanma Barranquero:

> Patch them :)

> You need CVS (which you already have) and a patch.exe (there are a few, from GnuWin32, MinGW, UnxUtils and Cygwin; I'd recommend *not* using the Cygwin one).

> When you've done some changes to your Emacs source tree, you go to the root and do a "cvs diff". For example, if your source tree is at C:\emacs\HEAD, do:

>           C:\> CD \emacs\HEAD
>           C:\emacs\HEAD> cvs diff -u2 > C:\emacs\my.patch

> Notes:

> - Of course, you could use other arguments for "cvs diff" (I like to happen unified diffs with 2-line contexts, but some people prefers context diffs, so that would be: "cvs diff -c > C:\emacs\my.patch").
> - If you always use the same arguments for "cvs diff", you can put them at .cvsrc on your HOME directory (see the docs for CVS). You can override them at the command line; for example, I have "-u2" on .cvsrc, but I can make context diffs with "cvs -f diff -c" (-f meaning "ignore .cvsrc").
> - Don't forget to redirect the output of "cvs diff" to a file *outside* the source tree.
> - If you have many changes in your source tree and you want to make a patch file for only some of them, for example only for a subdirectory of the source tree, do *not* move to the subdirectory. Instead of:

>                 C:\emacs\HEAD> cd lisp
>                 C:\emacs\HEAD\lisp> cvs diff > C:\emacs\my.patch

>   do this:

>                 C:\emacs\HEAD> cvs diff lisp > C:\emacs\my.patch

>   or, if only a few files:

>                 C:\emacs\HEAD> cvs diff src\w32fns.c src\w32term.c > C:\emacs\my.patch

>   *ALWAYS* from the root of the source tree. This way the patches are easier to apply and remove.

> Now, let's suppose I receive your patch file my.patch. My source tree is at C:\bin\emacs\gcc so I copy your file to C:\bin\emacs\my.patch. Then:

>           C:\bin\emacs\gcc> patch -p0 < C:\bin\emacs\my.patch

> And, supposing there's no conflict, now your patches are applied to my source tree. I can build it and test it normally. After a while, I want to remove your patch from my source tree, so I do:

>           C:\bin\emacs\gcc> patch -p0 -R < C:\bin\emacs\my.patch

> and voilą!

>> Should everything go into one .diff file?

> Yeah. Otherwise people will have to remember that several patch files correspond to the same bug/feature, and patch them one by one.

## Patches for the Emacs+EmacsW32 distribution

Installation programs for Emacs+EmacsW32 at http://OurComments.org/ are available in two versions, one with a slightly patched Emacs and one without patches. (See the home page for more information.) The files with names like readmve-CvsP060415.txt contains information about where to find the patches. Both this file and the patches are available both on the web site and in the installed Emacs+EmacsW32.