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