mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-11-26 07:33:47 +00:00
3c55fbd4ad
cae528457c; Add 2023 to copyright years.b394359261Improve documentation of 'isearch-open-overlay-temporary'ab3210e709Document 'use-package' in the 2 main manuals # Conflicts: # etc/refcards/ru-refcard.tex # lib/explicit_bzero.c # m4/explicit_bzero.m4
308 lines
12 KiB
Plaintext
308 lines
12 KiB
Plaintext
Copyright (C) 2001-2023 Free Software Foundation, Inc.
|
||
See the end of the file for license conditions.
|
||
|
||
Emacs version 30.0.50 for MS-Windows
|
||
|
||
This README file describes how to set up and run a precompiled
|
||
distribution of the latest version of GNU Emacs for MS-Windows. You
|
||
can find the precompiled distribution on the ftp.gnu.org server and
|
||
its mirrors:
|
||
|
||
https://ftp.gnu.org/gnu/emacs/windows/
|
||
|
||
This server contains other distributions, including the full Emacs
|
||
source distribution, as well as older releases of Emacs for Windows.
|
||
|
||
Information on how to compile Emacs from sources on Windows is in
|
||
the files README and INSTALL in the nt/ sub-directory of the
|
||
top-level Emacs directory in the source distribution, as is this
|
||
file under the name README.W32. If you received this file as part
|
||
of the Emacs source distribution, and are looking for information on
|
||
how to build Emacs on MS-Windows, please read those 2 files and not
|
||
this one.
|
||
|
||
* Preliminaries
|
||
|
||
There are two binary distributions named
|
||
emacs-VER-x86_64.zip and emacs-VER-i686.zip,
|
||
where VER is the Emacs version. These are 64-bit and 32-bit builds,
|
||
respectively. If you are running a 32-bit version of MS-Windows,
|
||
you need to install the 32-bit build; users of 64-bit Windows can
|
||
use either build, but we recommend to install the 64-bit one, as it
|
||
will be able to edit larger buffers and will generally run faster.
|
||
|
||
The binary distribution has these top-level directories:
|
||
|
||
+ bin
|
||
+ libexec
|
||
+ share
|
||
+ var
|
||
|
||
* Setting up Emacs
|
||
|
||
To install Emacs, simply unpack the binary package into a directory
|
||
of your choice. If you use the Windows Explorer and its "Extract"
|
||
action, by default this will be in a top-level directory with the
|
||
same name as the zip file.
|
||
|
||
Emacs is completely portable. You can create your own shortcut to
|
||
runemacs.exe and place this wherever you find it convenient (the
|
||
desktop and/or the Taskbar), or run it from a USB or network drive
|
||
without copying or installing anything on the machine itself.
|
||
|
||
It is also possible, although not recommended to use the program
|
||
bin/addpm.exe which will place an icon for Emacs on the start page.
|
||
|
||
* Prerequisites for Windows 9X
|
||
|
||
The 32-bit build supports MS-Windows 9X (Windows 95/98/Me). To run
|
||
Emacs on these versions of Windows, you will need to have the
|
||
Microsoft Layer for Unicode (MSLU) installed. It can be downloaded
|
||
from the Microsoft site, and comes in a form of a single dynamic
|
||
library called UNICOWS.DLL. If this library is not accessible to
|
||
Emacs on Windows 9X, it will pop up a dialog saying that it cannot
|
||
find the UNICOWS library, and will refuse to start up.
|
||
|
||
* Starting Emacs
|
||
|
||
To run Emacs, simply select Emacs from the Start Menu, or invoke
|
||
runemacs.exe directly from Explorer or from a command prompt. This
|
||
will start Emacs in its default GUI mode, ready to use. If you have
|
||
never used Emacs before, you should follow the tutorial at this
|
||
point (select Emacs Tutorial from the Help menu), since Emacs is
|
||
quite different from ordinary Windows applications in many respects.
|
||
|
||
If you want to use Emacs in tty or character mode within a command
|
||
window, you can start it by typing "emacs -nw" at the command prompt.
|
||
(Obviously, you need to ensure that the Emacs bin subdirectory is in
|
||
your Path first, or specify the path to emacs.exe.) The -nw
|
||
(non-windowed) mode of operation is most useful if you have a telnet
|
||
server on your machine, allowing you to run Emacs remotely.
|
||
|
||
* EXE files included
|
||
|
||
Emacs comes with the following executable files in the bin directory.
|
||
|
||
+ emacs.exe - The main Emacs executable. As this is designed to run
|
||
as both a text-mode application (emacs -nw) and as a GUI application,
|
||
it will pop up a command prompt window if run directly from Explorer.
|
||
|
||
+ runemacs.exe - A wrapper for running Emacs as a GUI application
|
||
without popping up a command prompt window. If you create a
|
||
desktop shortcut for invoking Emacs, make it point to this
|
||
executable, not to emacs.exe. If you pin Emacs to the task bar,
|
||
edit the properties of the pinned shortcut (with Shift-right mouse
|
||
click) to point to this executable.
|
||
|
||
+ emacsclient.exe - A command-line client program that can
|
||
communicate with a running Emacs process. See the `Emacs Server'
|
||
node of the Emacs manual.
|
||
|
||
+ emacsclientw.exe - A version of emacsclient that does not open
|
||
a command-line window.
|
||
|
||
+ addpm.exe - A basic installer that adds Emacs to "Start" menus and
|
||
adds Emacs-related entries to the Windows Registry.
|
||
|
||
+ ctags.exe, etags.exe - Tools for generating tag files. See the
|
||
`Tags' node of the Emacs manual.
|
||
|
||
+ ebrowse.exe - A tool for generating C++ browse information. See the
|
||
`Ebrowse' manual.
|
||
|
||
Several helper programs are in a version-specific subdirectory of
|
||
the libexec directory:
|
||
|
||
+ cmdproxy.exe - Used internally by Emacs to work around problems with
|
||
the native shells in various versions of Windows.
|
||
|
||
+ ddeclient.exe - A tool for interacting with DDE servers. To be
|
||
invoked as "ddeclient SERVER [TOPIC]", where SERVER is the DDE
|
||
server name, and sends each line of its standard input to the DDE
|
||
server using the DdeClientTransaction API. This program is
|
||
supposed to be invoked via the 'call-process-region' Emacs
|
||
primitive.
|
||
|
||
+ hexl.exe - A tool for producing hex dumps of binary files. See the
|
||
`Editing Binary Files' node of the Emacs manual.
|
||
|
||
+ movemail.exe - A helper application for safely moving mail from
|
||
a mail spool or POP server to a local user mailbox. See the
|
||
`Movemail' node of the Emacs manual.
|
||
|
||
+ profile.exe - A helper program that generates periodic events for
|
||
profiling Emacs Lisp code.
|
||
|
||
+ update-game-score.exe - A utility for updating the score files of
|
||
Emacs games.
|
||
|
||
* Emacs without optional dependencies
|
||
|
||
The files emacs-VER-x86_64.zip and emacs-VER-i686.zip contain a
|
||
large number of optional dependencies for Emacs.
|
||
|
||
Emacs has a number of optional features which use these additional
|
||
dependencies. They enable support for the following:
|
||
|
||
- displaying inline images of many types (PNG, JPEG, GIF, TIFF, SVG)
|
||
- SSL/TLS secure network communications (HTTPS, IMAPS, etc.)
|
||
- HTML and XML parsing (necessary for the built-in EWW browser)
|
||
- built-in decompression of compressed text
|
||
|
||
If you do not want these files (if you have them already for
|
||
instance, or you want the smallest possible Emacs), then you may use
|
||
the files emacs-VER-x86_64-no-deps.zip or
|
||
emacs-VER-i686-no-deps.zip. The dependency files are also available
|
||
as emacs-MVER-x86_64-deps.zip and emacs-MVER-i686-deps.zip. Source
|
||
code for these dependencies is available as
|
||
emacs-26-deps-mingw-w64-src.zip.
|
||
|
||
All distributions of Emacs have built in support for XBM and
|
||
PPM/PGM/PBM images, and the libXpm library is bundled, providing XPM
|
||
support (required for color toolbar icons and splash screen).
|
||
Source for libXpm should be available from the same place from which
|
||
you got this binary distribution.
|
||
|
||
* Installing Emacs with an existing MSYS2 installation
|
||
|
||
You may also use Emacs with an existing MSYS2 installation by
|
||
unpacking the emacs-VER-x86_64-no-deps.zip over the MSYS2
|
||
distribution. You should not use the emacs-VER-x86_64.zip from this
|
||
site, as this will overwrite MSYS2 files (the dependency bundle
|
||
derives from MSYS2, but will be from a different version). You can
|
||
then use the 'pacman' utility to install dependencies.
|
||
|
||
Some of the optional libraries need to be of certain versions to
|
||
work with your Emacs binary. Make sure you install those versions
|
||
of dependencies, and no others. Emacs variables such as
|
||
libpng-version and libjpeg-version tell what versions of the
|
||
corresponding libraries are expected by Emacs. (We recommend that
|
||
you use the dependency bundle, where these issues are always
|
||
resolved.)
|
||
|
||
To install the optional libraries, start the MSYS2 Bash window and
|
||
type the following command:
|
||
|
||
pacman -S PACKAGES
|
||
|
||
where PACKAGES is the list of packages you want to install. The
|
||
full list is as follows:
|
||
|
||
mingw-w64-x86_64-giflib
|
||
mingw-w64-x86_64-gnutls
|
||
mingw-w64-x86_64-libjpeg-turbo
|
||
mingw-w64-x86_64-libpng
|
||
mingw-w64-x86_64-librsvg
|
||
mingw-w64-x86_64-libtiff
|
||
mingw-w64-x86_64-libxml2
|
||
mingw-w64-x86_64-xpm-nox
|
||
mingw-w64-x86_64-lcms2
|
||
|
||
You can type any subset of this list. When asked whether to proceed
|
||
with installation, answer Y.
|
||
|
||
Alternatively, you could install the packages manually from this
|
||
page:
|
||
|
||
https://sourceforge.net/projects/msys2/files/REPOS/MINGW/x86_64/
|
||
|
||
However, the packages there are not self-contained, so you will need
|
||
to manually download all their dependencies as well.
|
||
|
||
* Uninstalling Emacs
|
||
|
||
If you should need to uninstall Emacs, simply delete all the files
|
||
and subdirectories from the directory where it was unpacked (Emacs
|
||
does not install or update any files in system directories or
|
||
anywhere else).
|
||
|
||
If you ran the addpm.exe program to create the Start menu icon, this
|
||
can be removed by right-clicking and "Uninstall".
|
||
|
||
Finally, addpm.exe also creates a few registry entries; these can be
|
||
safely left, but if you really wish to remove them, all of the
|
||
settings are written under the Software\GNU\Emacs key in
|
||
HKEY_LOCAL_MACHINE, or if you didn't have administrator privileges
|
||
when you installed, the same key in HKEY_CURRENT_USER. Just delete
|
||
the whole Software\GNU\Emacs key.
|
||
|
||
* Troubleshooting
|
||
|
||
Some known problems and their solutions can be found in the file
|
||
etc\PROBLEMS in the unpacked Emacs distribution.
|
||
|
||
Virus scanners
|
||
|
||
Some virus scanners interfere with Emacs' use of subprocesses. If you
|
||
are unable to use subprocesses and you use Dr. Solomon's WinGuard or
|
||
McAfee's Vshield, turn off "Scan all files" (WinGuard) or "boot sector
|
||
scanning" (McAfee exclusion properties).
|
||
|
||
Windows 9X
|
||
|
||
On Windows 9X, make sure you have the UNICOWS.DLL library either in
|
||
the same directory where you have emacs.exe or in the directory
|
||
where system-wide DLLs are kept.
|
||
|
||
* Further information
|
||
|
||
The Emacs User manual describes Windows-specific issues in the
|
||
appendix named "Emacs and Microsoft Windows/MS-DOS". You can read
|
||
it in Emacs by typing
|
||
|
||
C-h r g Microsoft Windows RET
|
||
|
||
This appendix is also available (as part of the entire manual) at
|
||
|
||
https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Microsoft-Windows
|
||
|
||
In addition to the manual, there is a mailing list for help with
|
||
Emacs here:
|
||
|
||
https://lists.gnu.org/mailman/listinfo/help-gnu-emacs
|
||
|
||
To ask questions on this mailing list, send email to
|
||
help-gnu-emacs@gnu.org.
|
||
|
||
A mailing list for issues specifically related to the MS-Windows port
|
||
of Emacs is here:
|
||
|
||
https://lists.gnu.org/mailman/listinfo/help-emacs-windows
|
||
|
||
To ask questions on this mailing list, send email to
|
||
help-emacs-windows@gnu.org.
|
||
|
||
* Reporting bugs
|
||
|
||
If you encounter a bug in this port of Emacs, we would like to hear
|
||
about it. First check the FAQ on the web page above to see if the bug
|
||
is already known and if there are any workarounds. Then check whether
|
||
the bug has something to do with code in your `.emacs' file, e.g. by
|
||
invoking Emacs with the "-Q" option.
|
||
|
||
If you decide that it is a bug in Emacs, use the built in bug
|
||
reporting facility to report it (from the menu: Help -> Send Bug Report).
|
||
If you have not yet configured Emacs for mail, then when you press
|
||
C-c C-c to send the report, it will ask you to paste the text of the
|
||
report into your mail client. If the bug is related to subprocesses,
|
||
also specify which shell you are using (e.g., include the values of
|
||
`shell-file-name' and `explicit-shell-file-name' in your message).
|
||
|
||
Enjoy!
|
||
|
||
|
||
This file is part of GNU Emacs.
|
||
|
||
GNU Emacs is free software: you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation, either version 3 of the License, or
|
||
(at your option) any later version.
|
||
|
||
GNU Emacs is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU General Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License
|
||
along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
|