nt/README.W32

   1 Copyright (C) 2001-2022 Free Software Foundation, Inc.
   2 See the end of the file for license conditions.
   3
   4                 Emacs version 28.0.91 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 \f
 294 This file is part of GNU Emacs.
 295
 296 GNU Emacs is free software: you can redistribute it and/or modify
 297 it under the terms of the GNU General Public License as published by
 298 the Free Software Foundation, either version 3 of the License, or
 299 (at your option) any later version.
 300
 301 GNU Emacs is distributed in the hope that it will be useful,
 302 but WITHOUT ANY WARRANTY; without even the implied warranty of
 303 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 304 GNU General Public License for more details.
 305
 306 You should have received a copy of the GNU General Public License
 307 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.