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