Usage notes for emacs on Cygwin
===============================

1. The emacs-basic, emacs-w32, emacs-X11, and emacs-lucid packages
   each provide an emacs binary.  These are emacs-basic.exe,
   emacs-w32.exe, emacs-gtk.exe, and emacs-lucid.exe, respectively, in
   order of increasing "priority".  The postinstall scripts create a
   symlink /usr/bin/emacs that resolves to the highest-priority binary
   that you have installed.  Thus the command 'emacs' will start
   emacs-lucid.exe if you've installed the emacs-lucid package;
   otherwise, it will start emacs-gtk.exe if you've installed
   emacs-gtk; otherwise, it will start emacs-w32.exe if you've
   installed emacs-w32; otherwise, it will start emacs-basic.exe.
   Similar remarks apply to emacsclient.

   If you have installed more than one of the binary packages and
   don't like the default resolution of /usr/bin/emacs, you can run
   one of the /usr/bin/set-emacs-default-*.sh scripts to change it.
   For example,

     /usr/bin/set-emacs-default-w32.sh

   will make /usr/bin/emacs resolve to /usr/bin/emacs-w32.exe,
   regardless of which packages you've installed.

2. Install emacs-gtk if you want to use the X11 GUI with the GTK+
   toolkit.  You can then type 'emacs&' in an xterm window, and
   emacs-gtk.exe will start in a new window.  If you prefer the Lucid
   toolkit, install emacs-lucid instead.

3. Install emacs-w32 if you want to use the native Windows GUI instead
   of X11.

4. Install emacs-basic if you want a minimal emacs with no GUI.

5. If you use the Emacs MH-E library for email, consider installing
   Cygwin's mailutils-mh package.  To use it, put the line

     (load "mailutils-mh")

   in your site-start.el or ~/.emacs file.

6. If you have sshd running and want to be able to run emacs-gtk or
   emacs-lucid from a remote machine, you need to enable X11
   forwarding by adding the following line to /etc/sshd_config:

     X11Forwarding yes

   You might also need to have the cygserver service running.

7. The script /usr/bin/make-emacs-shortcut can be used to create a
   shortcut for starting emacs.  The shortcut assumes that you have
   installed the emacs-gtk and emacs-w32 packages.  It starts
   emacs-gtk under X if an X server is running, and it starts
   emacs-w32.exe otherwise.  The script creates an xml file in
   /usr/local/bin, so the user who runs the script needs to be able to
   write to that directory.

   Edit the shortcut or the script or the xml file if you want to
   modify the default behavior.

   You will need the cygutils package in order to run
   make-emacs-shortcut, and you will need the run2 package in order to
   use the shortcut it creates.

8. If you don't like the default fonts in the GUI versions of emacs,
   you can change them via the menu items

     Options -> Set Default Font
     Options -> Save Options

   This will set the default font in your ~/.emacs and will apply to
   all GUI versions of emacs.  If you want different default fonts for
   the w32 and X11 GUIs, use the lisp variable `window-system' to
   distinguish between them.

   For example, the following code in ~/.emacs makes DejaVu Sans
   Mono-10 the default font for emacs-w32:

     (if (eq window-system 'w32)
         (add-to-list 'default-frame-alist
                      '(font . "DejaVu Sans Mono-10")))

   And the following code in ~/.emacs makes DejaVu Sans Mono-10 the
   default for emacs-w32 and Droid Sans Mono-11 the default for
   emacs-gtk and emacs-lucid:

     (cond
      ((eq window-system 'w32)
       (add-to-list 'default-frame-alist
                    '(font . "DejaVu Sans Mono-10")))
      ((eq window-system 'x)
       (add-to-list 'default-frame-alist
                    '(font . "Droid Sans Mono-11"))))

9. If you want to run emacs under gdb, start by giving the following
   gdb command:

     (gdb) source /usr/share/emacs/<version>/etc/.gdbinit

   This defines some gdb commands that are helpful when debugging
   emacs.  See /usr/share/emacs/<version>/etc/DEBUG for details.

10. This release has been built with the native compilation feature,
    which we explain briefly:

    Many of the editing commands used in Emacs are defined in elisp
    libraries (*.el files).  To make Emacs run faster, these libraries
    are usually compiled to architecture-independent *.elc files,
    containing "byte-code" representations of the functions in the
    original files.  These byte-code functions are interpreted by the
    Emacs "byte-code interpreter" when they are called.

    Native compilation takes this one step further by using gcc to
    compile the elisp libraries to native shared libraries (like DLLs,
    but with an extension .eln instead of .dll).  This results in a
    substantial speed-up of Emacs.

    Some of the .eln files are created at build time.  These are
    installed in a subdirectory of

      /usr/lib/emacs/<version>/native-lisp.

    Others are created as needed and are stored by default in a
    subdirectory of ~/.emacs.d/eln-cache.

    The first few times you run Emacs, it might seem slow to start.
    This is because it is compiling the elisp libraries that are
    needed for your init file (usually .emacs).  For the same reason,
    you might see occasional pauses the first time you use a command.
    But otherwise you should see a noticeable speed-up of Emacs.

    The .eln files have been built with ASLR[1] enabled.  The hope is
    that this eliminates the fork failures (and the need to rebase)
    that were present in previous releases with native compilation.

11. One interesting new feature of Emacs-29 is that it is built with
    the tree-sitter parsing library.  See the NEWS file ('C-h n'
    within emacs) for details.  As explained there, you need grammar
    libraries in order to use this feature.  These can be built and
    installed via the 'treesit-install-language-grammar' command.  If
    you build them this way, they will be built with ASLR[1] enabled,
    which I hope will prevent fork failures.

[1] https://www.mandiant.com/resources/blog/six-facts-about-address-space-layout-randomization-on-windows
