| 1 | Copyright (C) 2001-2013 Free Software Foundation, Inc. |
| 2 | See the end of the file for license conditions. |
| 3 | |
| 4 | Emacs for Windows |
| 5 | |
| 6 | This README.W32 file describes how to set up and run a precompiled |
| 7 | distribution of GNU Emacs for Windows. You can find the precompiled |
| 8 | distribution on the ftp.gnu.org server and its mirrors: |
| 9 | |
| 10 | ftp://ftp.gnu.org/gnu/emacs/windows/ |
| 11 | |
| 12 | This server contains other distributions, including the full Emacs |
| 13 | source distribution and a barebin distribution which can be installed |
| 14 | over it, as well as older releases of Emacs for Windows. |
| 15 | |
| 16 | Information on how to compile Emacs from sources on Windows is in |
| 17 | the files README and INSTALL in this directory. If you received |
| 18 | this file as part of the Emacs source distribution, please read |
| 19 | those 2 files and not this one. |
| 20 | |
| 21 | * Preliminaries |
| 22 | |
| 23 | Along with this file should be six subdirectories (bin, etc, info, |
| 24 | lisp, leim, site-lisp). If you have downloaded the barebin |
| 25 | distribution, then it will contain only the bin directory and the |
| 26 | built in documentation in etc/DOC, the rest of the subdirectories |
| 27 | are in the src distribution, which the barebin distribution is |
| 28 | designed to be used with. |
| 29 | |
| 30 | * Setting up Emacs |
| 31 | |
| 32 | To install Emacs, simply unpack all the files into a directory of |
| 33 | your choice, but note that you might encounter minor problems if |
| 34 | there is a space anywhere in the directory name. To complete the |
| 35 | installation process, you can optionally run the program addpm.exe |
| 36 | in the bin subdirectory. This will put an icon for Emacs in the |
| 37 | Start Menu under "Start -> Programs -> Gnu Emacs". |
| 38 | |
| 39 | Some users have reported that the Start Menu item is not created for |
| 40 | them. If this happens, just create your own shortcut to runemacs.exe, |
| 41 | eg. by dragging it on to the desktop or the Start button. |
| 42 | |
| 43 | Note that running addpm is now an optional step; Emacs is able to |
| 44 | locate all of its files without needing any information to be set in |
| 45 | the environment or the registry, although such settings will still |
| 46 | be obeyed if present. This is convenient for running Emacs on a |
| 47 | machine which disallows registry changes, or on which software |
| 48 | should not be installed. For instance, you can now run Emacs |
| 49 | directly from a CD or USB flash drive without copying or installing |
| 50 | anything on the machine itself. |
| 51 | |
| 52 | * Prerequisites for Windows 9X |
| 53 | |
| 54 | To run Emacs on Windows 9X (Windows 95/98/Me), you will need to have |
| 55 | the Microsoft Layer for Unicode (MSLU) installed. It can be |
| 56 | downloaded from the Microsoft site, and comes in a form of a single |
| 57 | dynamic library called UNICOWS.DLL. If this library is not |
| 58 | accessible to Emacs, it will pop up a dialog saying that it cannot |
| 59 | find the library, and will refuse to start up a GUI session. |
| 60 | (However, it is still possible to use Emacs in text mode, even |
| 61 | without UNICOWS.DLL, by invoking it as "emacs -nw", see below.) |
| 62 | |
| 63 | * Starting Emacs |
| 64 | |
| 65 | To run Emacs, simply select Emacs from the Start Menu, or invoke |
| 66 | runemacs.exe directly from Explorer or from a command prompt. This |
| 67 | will start Emacs in its default GUI mode, ready to use. If you have |
| 68 | never used Emacs before, you should follow the tutorial at this |
| 69 | point (select Emacs Tutorial from the Help menu), since Emacs is |
| 70 | quite different from ordinary Windows applications in many respects. |
| 71 | |
| 72 | If you want to use Emacs in tty or character mode within a command |
| 73 | window, you can start it by typing "emacs -nw" at the command prompt. |
| 74 | (Obviously, you need to ensure that the Emacs bin subdirectory is in |
| 75 | your PATH first, or specify the path to emacs.exe.) The -nw |
| 76 | (non-windowed) mode of operation is most useful if you have a telnet |
| 77 | server on your machine, allowing you to run Emacs remotely. |
| 78 | |
| 79 | * EXE files included |
| 80 | |
| 81 | Emacs comes with the following executable files in the bin directory. |
| 82 | |
| 83 | + emacs.exe - The main Emacs executable. As this is designed to run |
| 84 | as both a text-mode application (emacs -nw) and as a GUI application, |
| 85 | it will pop up a command prompt window if run directly from Explorer. |
| 86 | |
| 87 | + runemacs.exe - A wrapper for running Emacs as a GUI application |
| 88 | without popping up a command prompt window. If you create a |
| 89 | desktop shortcut for invoking Emacs, make it point to this |
| 90 | executable, not to emacs.exe. |
| 91 | |
| 92 | + emacsclient.exe - A command-line client program that can |
| 93 | communicate with a running Emacs process. See the `Emacs Server' |
| 94 | node of the Emacs manual. |
| 95 | |
| 96 | + emacsclientw.exe - A version of emacsclient that does not open |
| 97 | a command-line window. |
| 98 | |
| 99 | + addpm.exe - A basic installer that creates Start Menu icons for Emacs. |
| 100 | Running this is optional. |
| 101 | |
| 102 | + cmdproxy.exe - Used internally by Emacs to work around problems with |
| 103 | the native shells in various versions of Windows. |
| 104 | |
| 105 | + ctags.exe, etags.exe - Tools for generating tag files. See the |
| 106 | `Tags' node of the Emacs manual. |
| 107 | |
| 108 | + ebrowse.exe - A tool for generating C++ browse information. See the |
| 109 | `Ebrowse' manual. |
| 110 | |
| 111 | + ddeclient.exe - A tool for interacting with DDE servers. To be |
| 112 | invoked as "ddeclient SERVER [TOPIC]", where SERVER is the DDE |
| 113 | server name, and sends each line of its standard input to the DDE |
| 114 | server using the DdeClientTransaction API. This program is |
| 115 | supposed to be invoked via the 'call-process-region' Emacs |
| 116 | primitive. |
| 117 | |
| 118 | + hexl.exe - A tool for producing hex dumps of binary files. See the |
| 119 | `Editing Binary Files' node of the Emacs manual. |
| 120 | |
| 121 | + movemail.exe - A helper application for safely moving mail from |
| 122 | a mail spool or POP server to a local user mailbox. See the |
| 123 | `Movemail' node of the Emacs manual. |
| 124 | |
| 125 | * Image support |
| 126 | |
| 127 | Emacs has built in support for XBM and PPM/PGM/PBM images, and the |
| 128 | libXpm library is bundled, providing XPM support (required for color |
| 129 | toolbar icons and splash screen). Source for libXpm should be available |
| 130 | on the same place as you got this binary distribution from. |
| 131 | |
| 132 | Emacs can also support some other image formats with appropriate |
| 133 | libraries. These libraries are all available as part of GTK |
| 134 | download for Windows (http://www.gtk.org/download/win32.php), or |
| 135 | from the GnuWin32 project. Emacs will find them if the directory |
| 136 | they are installed in is on the PATH. |
| 137 | |
| 138 | PNG: requires the PNG reference library 1.4 or later, which will |
| 139 | be named libpng14.dll or libpng14-14.dll. LibPNG requires zlib, |
| 140 | which should come from the same source as you got libpng. |
| 141 | Starting with Emacs 23.3, the precompiled Emacs binaries are |
| 142 | built with libpng 1.4.x and later, and are incompatible with |
| 143 | earlier versions of libpng DLLs. So if you have libpng 1.2.x, |
| 144 | the PNG support will not work, and you will have to download |
| 145 | newer versions. |
| 146 | |
| 147 | JPEG: requires the Independent JPEG Group's libjpeg 6b or later, |
| 148 | which will be called jpeg62.dll, libjpeg.dll, jpeg-62.dll or jpeg.dll. |
| 149 | |
| 150 | TIFF: requires libTIFF 3.0 or later, which will be called libtiff3.dll |
| 151 | or libtiff.dll. |
| 152 | |
| 153 | GIF: requires libungif or giflib 4.1 or later, which will be |
| 154 | called giflib4.dll, libungif4.dll or libungif.dll. |
| 155 | |
| 156 | If you have image support DLLs under different names, customize the |
| 157 | value of `dynamic-library-alist'. |
| 158 | |
| 159 | In addition, Emacs can be compiled to support SVG. This precompiled |
| 160 | distribution has not been compiled that way, since the SVG library |
| 161 | or one or more of its extensive dependencies appear to be |
| 162 | unreliable under Windows. See nt/INSTALL in the src distribution if |
| 163 | you wish to compile Emacs with SVG support. |
| 164 | |
| 165 | * GnuTLS support |
| 166 | |
| 167 | In order to support GnuTLS at runtime, Emacs must be able to find |
| 168 | the relevant DLLs during startup; failure to do so is not an error, |
| 169 | but GnuTLS won't be available to the running session. |
| 170 | |
| 171 | You can get pre-built binaries (including any required DLL and the |
| 172 | header files) at http://sourceforge.net/projects/ezwinports/files/. |
| 173 | |
| 174 | * libxml2 support |
| 175 | |
| 176 | In order to support libxml2 at runtime, a libxml2-enabled Emacs must |
| 177 | be able to find the relevant DLLs during startup; failure to do so |
| 178 | is not an error, but libxml2 features won't be available to the |
| 179 | running session. |
| 180 | |
| 181 | You can get pre-built binaries (including any required DLL and the |
| 182 | header files) at http://sourceforge.net/projects/ezwinports/files/. |
| 183 | |
| 184 | * Uninstalling Emacs |
| 185 | |
| 186 | If you should need to uninstall Emacs, simply delete all the files |
| 187 | and subdirectories from the directory where it was unpacked (Emacs |
| 188 | does not install or update any files in system directories or |
| 189 | anywhere else). If you ran the addpm.exe program to create the |
| 190 | registry entries and the Start menu icon, then you can remove the |
| 191 | registry entries using regedit. All of the settings are written |
| 192 | under the Software\GNU\Emacs key in HKEY_LOCAL_MACHINE, or if you |
| 193 | didn't have administrator privileges when you installed, the same |
| 194 | key in HKEY_CURRENT_USER. Just delete the whole Software\GNU\Emacs |
| 195 | key. |
| 196 | |
| 197 | The Start menu entry can be removed by right-clicking on the Task bar |
| 198 | and selecting Properties, then using the Remove option on the Start |
| 199 | Menu Programs page. (If you installed under an account with |
| 200 | administrator privileges, then you need to click the Advanced button |
| 201 | and look for the Gnu Emacs menu item under All Users.) |
| 202 | |
| 203 | * Troubleshooting |
| 204 | |
| 205 | Unpacking the distributions |
| 206 | |
| 207 | If you encounter trouble trying to run Emacs, there are a number of |
| 208 | possible causes. Check the following for indications that the |
| 209 | distribution was not corrupted by the tools used to unpack it: |
| 210 | |
| 211 | * Be sure to disable CR/LF translation or the executables will |
| 212 | be unusable. Older versions of WinZipNT would enable this |
| 213 | translation by default. If you are using WinZipNT, disable it. |
| 214 | (I don't have WinZipNT myself, and I do not know the specific |
| 215 | commands necessary to disable it.) |
| 216 | |
| 217 | * Check that filenames were not truncated to 8.3. For example, |
| 218 | there should be a file lisp\abbrevlist.elc; if this has been |
| 219 | truncated to abbrevli.elc, your distribution has been corrupted |
| 220 | while unpacking and Emacs will not start. |
| 221 | |
| 222 | * On Windows 9X, make sure you have the UNICOWS.DLL library either |
| 223 | in the same directory where you have emacs.exe or in the |
| 224 | directory where system-wide DLLs are kept. |
| 225 | |
| 226 | If you believe you have unpacked the distributions correctly and are |
| 227 | still encountering problems, see the section on Further Information |
| 228 | below. |
| 229 | |
| 230 | Virus scanners |
| 231 | |
| 232 | Some virus scanners interfere with Emacs' use of subprocesses. If you |
| 233 | are unable to use subprocesses and you use Dr. Solomon's WinGuard or |
| 234 | McAfee's Vshield, turn off "Scan all files" (WinGuard) or "boot sector |
| 235 | scanning" (McAfee exclusion properties). |
| 236 | |
| 237 | * Further information |
| 238 | |
| 239 | The FAQ for the MS Windows port of Emacs is distributed with Emacs |
| 240 | (info manual "efaq-w32"), and also available at |
| 241 | |
| 242 | http://www.gnu.org/software/emacs/manual/efaq-w32.html |
| 243 | |
| 244 | In addition to the FAQ, there is a mailing list for discussing issues |
| 245 | related to the Windows port of Emacs. For information about the |
| 246 | list, see this Web page: |
| 247 | |
| 248 | http://lists.gnu.org/mailman/listinfo/help-emacs-windows |
| 249 | |
| 250 | To ask questions on the mailing list, send email to |
| 251 | help-emacs-windows@gnu.org. (You don't need to subscribe for that.) |
| 252 | To subscribe to the list or unsubscribe from it, fill the form you |
| 253 | find at http://lists.gnu.org/mailman/listinfo/help-emacs-windows as |
| 254 | explained there. |
| 255 | |
| 256 | Another valuable source of information and help which should not be |
| 257 | overlooked is the various Usenet news groups dedicated to Emacs. |
| 258 | These are particularly good for help with general issues which aren't |
| 259 | specific to the Windows port of Emacs. The main news groups to use |
| 260 | for seeking help are: |
| 261 | |
| 262 | gnu.emacs.help |
| 263 | comp.emacs |
| 264 | |
| 265 | There are also fairly regular postings and announcements of new or |
| 266 | updated Emacs packages on this group: |
| 267 | |
| 268 | gnu.emacs.sources |
| 269 | |
| 270 | * Reporting bugs |
| 271 | |
| 272 | If you encounter a bug in this port of Emacs, we would like to hear |
| 273 | about it. First check the FAQ on the web page above to see if the bug |
| 274 | is already known and if there are any workarounds. Then check whether |
| 275 | the bug has something to do with code in your .emacs file, e.g. by |
| 276 | invoking Emacs with the "-Q" option. |
| 277 | |
| 278 | If you decide that it is a bug in Emacs, use the built in bug |
| 279 | reporting facility to report it (from the menu; Help -> Send Bug Report). |
| 280 | If you have not yet configured Emacs for mail, then when you press |
| 281 | C-c C-c to send the report, it will ask you to paste the text of the |
| 282 | report into your mail client. If the bug is related to subprocesses, |
| 283 | also specify which shell you are using (e.g., include the values of |
| 284 | `shell-file-name' and `explicit-shell-file-name' in your message). |
| 285 | |
| 286 | Enjoy! |
| 287 | |
| 288 | \f |
| 289 | This file is part of GNU Emacs. |
| 290 | |
| 291 | GNU Emacs is free software: you can redistribute it and/or modify |
| 292 | it under the terms of the GNU General Public License as published by |
| 293 | the Free Software Foundation, either version 3 of the License, or |
| 294 | (at your option) any later version. |
| 295 | |
| 296 | GNU Emacs is distributed in the hope that it will be useful, |
| 297 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 298 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 299 | GNU General Public License for more details. |
| 300 | |
| 301 | You should have received a copy of the GNU General Public License |
| 302 | along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. |