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