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. 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
