admin/nt/README.W32

   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
   5                            Emacs for Windows
   6
   7   This README file describes how to set up and run a precompiled version
   8   of GNU Emacs for Windows NT/2000/XP and Windows 95/98/Me.  This
   9   distribution can be found on the ftp.gnu.org server and its mirrors:
  10
  11         ftp://ftp.gnu.org/gnu/emacs/windows/
  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
  19   http:
  20
  21         http://www.gnu.org/software/emacs/windows/ntemacs.html
  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
  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
 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
 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.
 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
 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
 212   related to the Windows port of Emacs.  For information about the
 213   list, see this Web page:
 214
 215         http://lists.gnu.org/mailman/listinfo/help-emacs-windows
 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
 220   find at http://lists.gnu.org/mailman/listinfo/help-emacs-windows as
 221   explained there.
 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
 246   Windows port, send a message to the "help-emacs-windows@gnu.org"
 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,
 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).
 253
 254   If you think the bug is not specific to the Windows port of Emacs,
 255   then it is better to mail the bug report to "bug-gnu-emacs@gnu.org" so
 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
 262   Enjoy!
 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 of the License, or
 270 (at your option) 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.  If not, see <http://www.gnu.org/licenses/>.