1Copyright (C) 2001-2021 Free Software Foundation, Inc. 2See the end of the file for license conditions. 3 4 Emacs version 29.0.50 for MS-Windows 5 6 This README file describes how to set up and run a precompiled 7 distribution of the latest version of GNU Emacs for MS-Windows. You 8 can find the precompiled distribution on the ftp.gnu.org server and 9 its mirrors: 10 11 https://ftp.gnu.org/gnu/emacs/windows/ 12 13 This server contains other distributions, including the full Emacs 14 source distribution, 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 the nt/ sub-directory of the 18 top-level Emacs directory in the source distribution, as is this 19 file under the name README.W32. If you received this file as part 20 of the Emacs source distribution, and are looking for information on 21 how to build Emacs on MS-Windows, please read those 2 files and not 22 this one. 23 24* Preliminaries 25 26 There are two binary distributions named 27 emacs-VER-x86_64.zip and emacs-VER-i686.zip, 28 where VER is the Emacs version. These are 64-bit and 32-bit builds, 29 respectively. If you are running a 32-bit version of MS-Windows, 30 you need to install the 32-bit build; users of 64-bit Windows can 31 use either build, but we recommend to install the 64-bit one, as it 32 will be able to edit larger buffers and will generally run faster. 33 34 The binary distribution has these top-level directories: 35 36 + bin 37 + libexec 38 + share 39 + var 40 41* Setting up Emacs 42 43 To install Emacs, simply unpack the binary package into a directory 44 of your choice. If you use the Windows Explorer and its "Extract" 45 action, by default this will be in a top-level directory with the 46 same name as the zip file. 47 48 Emacs is completely portable. You can create your own shortcut to 49 runemacs.exe and place this wherever you find it convenient (the 50 desktop and/or the Taskbar), or run it from a USB or network drive 51 without copying or installing anything on the machine itself. 52 53 It is also possible, although not recommended to use the program 54 bin/addpm.exe which will place an icon for Emacs on the start page. 55 56* Prerequisites for Windows 9X 57 58 The 32-bit build supports MS-Windows 9X (Windows 95/98/Me). To run 59 Emacs on these versions of Windows, you will need to have the 60 Microsoft Layer for Unicode (MSLU) installed. It can be downloaded 61 from the Microsoft site, and comes in a form of a single dynamic 62 library called UNICOWS.DLL. If this library is not accessible to 63 Emacs on Windows 9X, it will pop up a dialog saying that it cannot 64 find the UNICOWS library, and will refuse to start up. 65 66* Starting Emacs 67 68 To run Emacs, simply select Emacs from the Start Menu, or invoke 69 runemacs.exe directly from Explorer or from a command prompt. This 70 will start Emacs in its default GUI mode, ready to use. If you have 71 never used Emacs before, you should follow the tutorial at this 72 point (select Emacs Tutorial from the Help menu), since Emacs is 73 quite different from ordinary Windows applications in many respects. 74 75 If you want to use Emacs in tty or character mode within a command 76 window, you can start it by typing "emacs -nw" at the command prompt. 77 (Obviously, you need to ensure that the Emacs bin subdirectory is in 78 your Path first, or specify the path to emacs.exe.) The -nw 79 (non-windowed) mode of operation is most useful if you have a telnet 80 server on your machine, allowing you to run Emacs remotely. 81 82* EXE files included 83 84 Emacs comes with the following executable files in the bin directory. 85 86 + emacs.exe - The main Emacs executable. As this is designed to run 87 as both a text-mode application (emacs -nw) and as a GUI application, 88 it will pop up a command prompt window if run directly from Explorer. 89 90 + runemacs.exe - A wrapper for running Emacs as a GUI application 91 without popping up a command prompt window. If you create a 92 desktop shortcut for invoking Emacs, make it point to this 93 executable, not to emacs.exe. If you pin Emacs to the task bar, 94 edit the properties of the pinned shortcut (with Shift-right mouse 95 click) to point to this executable. 96 97 + emacsclient.exe - A command-line client program that can 98 communicate with a running Emacs process. See the `Emacs Server' 99 node of the Emacs manual. 100 101 + emacsclientw.exe - A version of emacsclient that does not open 102 a command-line window. 103 104 + addpm.exe - A basic installer that adds Emacs to "Start" menus and 105 adds Emacs-related entries to the Windows Registry. 106 107 + ctags.exe, etags.exe - Tools for generating tag files. See the 108 `Tags' node of the Emacs manual. 109 110 + ebrowse.exe - A tool for generating C++ browse information. See the 111 `Ebrowse' manual. 112 113 Several helper programs are in a version-specific subdirectory of 114 the libexec directory: 115 116 + cmdproxy.exe - Used internally by Emacs to work around problems with 117 the native shells in various versions of Windows. 118 119 + ddeclient.exe - A tool for interacting with DDE servers. To be 120 invoked as "ddeclient SERVER [TOPIC]", where SERVER is the DDE 121 server name, and sends each line of its standard input to the DDE 122 server using the DdeClientTransaction API. This program is 123 supposed to be invoked via the 'call-process-region' Emacs 124 primitive. 125 126 + hexl.exe - A tool for producing hex dumps of binary files. See the 127 `Editing Binary Files' node of the Emacs manual. 128 129 + movemail.exe - A helper application for safely moving mail from 130 a mail spool or POP server to a local user mailbox. See the 131 `Movemail' node of the Emacs manual. 132 133 + profile.exe - A helper program that generates periodic events for 134 profiling Emacs Lisp code. 135 136 + update-game-score.exe - A utility for updating the score files of 137 Emacs games. 138 139* Emacs without optional dependencies 140 141 The files emacs-VER-x86_64.zip and emacs-VER-i686.zip contain a 142 large number of optional dependencies for Emacs. 143 144 Emacs has a number of optional features which use these additional 145 dependencies. They enable support for the following: 146 147 - displaying inline images of many types (PNG, JPEG, GIF, TIFF, SVG) 148 - SSL/TLS secure network communications (HTTPS, IMAPS, etc.) 149 - HTML and XML parsing (necessary for the built-in EWW browser) 150 - built-in decompression of compressed text 151 152 If you do not want these files (if you have them already for 153 instance, or you want the smallest possible Emacs), then you may use 154 the files emacs-VER-x86_64-no-deps.zip or 155 emacs-VER-i686-no-deps.zip. The dependency files are also available 156 as emacs-MVER-x86_64-deps.zip and emacs-MVER-i686-deps.zip. Source 157 code for these dependencies is available as 158 emacs-26-deps-mingw-w64-src.zip. 159 160 All distributions of Emacs have built in support for XBM and 161 PPM/PGM/PBM images, and the libXpm library is bundled, providing XPM 162 support (required for color toolbar icons and splash screen). 163 Source for libXpm should be available from the same place from which 164 you got this binary distribution. 165 166* Installing Emacs with an existing MSYS2 installation 167 168 You may also use Emacs with an existing MSYS2 installation by 169 unpacking the emacs-VER-x86_64-no-deps.zip over the MSYS2 170 distribution. You should not use the emacs-VER-x86_64.zip from this 171 site, as this will overwrite MSYS2 files (the dependency bundle 172 derives from MSYS2, but will be from a different version). You can 173 then use the 'pacman' utility to install dependencies. 174 175 Some of the optional libraries need to be of certain versions to 176 work with your Emacs binary. Make sure you install those versions 177 of dependencies, and no others. Emacs variables such as 178 libpng-version and libjpeg-version tell what versions of the 179 corresponding libraries are expected by Emacs. (We recommend that 180 you use the dependency bundle, where these issues are always 181 resolved.) 182 183 To install the optional libraries, start the MSYS2 Bash window and 184 type the following command: 185 186 pacman -S PACKAGES 187 188 where PACKAGES is the list of packages you want to install. The 189 full list is as follows: 190 191 mingw-w64-x86_64-giflib 192 mingw-w64-x86_64-gnutls 193 mingw-w64-x86_64-libjpeg-turbo 194 mingw-w64-x86_64-libpng 195 mingw-w64-x86_64-librsvg 196 mingw-w64-x86_64-libtiff 197 mingw-w64-x86_64-libxml2 198 mingw-w64-x86_64-xpm-nox 199 mingw-w64-x86_64-lcms2 200 201 You can type any subset of this list. When asked whether to proceed 202 with installation, answer Y. 203 204 Alternatively, you could install the packages manually from this 205 page: 206 207 https://sourceforge.net/projects/msys2/files/REPOS/MINGW/x86_64/ 208 209 However, the packages there are not self-contained, so you will need 210 to manually download all their dependencies as well. 211 212* Uninstalling Emacs 213 214 If you should need to uninstall Emacs, simply delete all the files 215 and subdirectories from the directory where it was unpacked (Emacs 216 does not install or update any files in system directories or 217 anywhere else). 218 219 If you ran the addpm.exe program to create the Start menu icon, this 220 can be removed by right-clicking and "Uninstall". 221 222 Finally, addpm.exe also creates a few registry entries; these can be 223 safely left, but if you really wish to remove them, all of the 224 settings are written under the Software\GNU\Emacs key in 225 HKEY_LOCAL_MACHINE, or if you didn't have administrator privileges 226 when you installed, the same key in HKEY_CURRENT_USER. Just delete 227 the whole Software\GNU\Emacs key. 228 229* Troubleshooting 230 231 Some known problems and their solutions can be found in the file 232 etc\PROBLEMS in the unpacked Emacs distribution. 233 234 Virus scanners 235 236 Some virus scanners interfere with Emacs' use of subprocesses. If you 237 are unable to use subprocesses and you use Dr. Solomon's WinGuard or 238 McAfee's Vshield, turn off "Scan all files" (WinGuard) or "boot sector 239 scanning" (McAfee exclusion properties). 240 241 Windows 9X 242 243 On Windows 9X, make sure you have the UNICOWS.DLL library either in 244 the same directory where you have emacs.exe or in the directory 245 where system-wide DLLs are kept. 246 247* Further information 248 249 The Emacs User manual describes Windows-specific issues in the 250 appendix named "Emacs and Microsoft Windows/MS-DOS". You can read 251 it in Emacs by typing 252 253 C-h r g Microsoft Windows RET 254 255 This appendix is also available (as part of the entire manual) at 256 257 https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Microsoft-Windows 258 259 In addition to the manual, there is a mailing list for help with 260 Emacs here: 261 262 https://lists.gnu.org/mailman/listinfo/help-gnu-emacs 263 264 To ask questions on this mailing list, send email to 265 help-gnu-emacs@gnu.org. 266 267 A mailing list for issues specifically related to the MS-Windows port 268 of Emacs is here: 269 270 https://lists.gnu.org/mailman/listinfo/help-emacs-windows 271 272 To ask questions on this mailing list, send email to 273 help-emacs-windows@gnu.org. 274 275* Reporting bugs 276 277 If you encounter a bug in this port of Emacs, we would like to hear 278 about it. First check the FAQ on the web page above to see if the bug 279 is already known and if there are any workarounds. Then check whether 280 the bug has something to do with code in your `.emacs' file, e.g. by 281 invoking Emacs with the "-Q" option. 282 283 If you decide that it is a bug in Emacs, use the built in bug 284 reporting facility to report it (from the menu: Help -> Send Bug Report). 285 If you have not yet configured Emacs for mail, then when you press 286 C-c C-c to send the report, it will ask you to paste the text of the 287 report into your mail client. If the bug is related to subprocesses, 288 also specify which shell you are using (e.g., include the values of 289 `shell-file-name' and `explicit-shell-file-name' in your message). 290 291 Enjoy! 292 293 294This file is part of GNU Emacs. 295 296GNU Emacs is free software: you can redistribute it and/or modify 297it under the terms of the GNU General Public License as published by 298the Free Software Foundation, either version 3 of the License, or 299(at your option) any later version. 300 301GNU Emacs is distributed in the hope that it will be useful, 302but WITHOUT ANY WARRANTY; without even the implied warranty of 303MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 304GNU General Public License for more details. 305 306You should have received a copy of the GNU General Public License 307along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. 308