Upgrading Emacs

= Upgrade steps =

ln --symbolic --no-dereference --force -- "$HOME/emacs-27.1-bin"  "$HOME/emacs-current"
 * Remove or rename all other Emacs versions from the system. Otherwise, you may get confused later on, when the wrong Emacs version accidentally starts when double-clicking on some file.
 * Get the new Emacs version.
 * Under Windows, use a precompiled binary, and place it somewhere so that the path does not contains spaces (just in case). Emacs looks for its configuration files under %APPDATA%.
 * Under Linux, build Emacs from source if you cannot find an appropriate source of pre-built binaries. See the building section below for details.
 * Create or update a symbolic link to refer to the new version. Because you will be upgrading Emacs every now and then, it is best use a symbolic link to point to the latest version. This way, you can comfortably switch versions:
 * If you have downloaded packages from a remote repository like MELPA in the past, now would be a good time to update them all. There are 2 options:
 * Option 1) Install package auto-package-update and run auto-package-update-now.
 * Option 2) Run list-packages, go to the "Package" menu, choose "Refresh Package List" (package-menu-refresh) just in case, then "Mark Upgradable Packages" (package-menu-mark-upgrades). If you are using Paradox instead of the default package manager, use Paradox/Filter Package List/By Upgrades (paradox-filter-upgrades) to conveniently filter by upgrades. Finally, "Execute Actions" (package-menu-execute).
 * If you are running Cygwin under Windows, you will probably want to install package cygwin-mount. If Cygwin is not in the PATH, this package will complain that it cannot found the 'mount tool' . Customize group "cygwin-mount", variable "Cygwin Mount Cygwin Bin Directory", and set it to the right path, for example "C:\cygwin64\bin".
 * Under Linux or Cygwin, change your $EDITOR shell variable. For example:

# Using "--no-wait" here will probably break some programs # that expect the user editing to have finished when # emacsclient exits. export EDITOR="$HOME/emacs-current/bin/emacsclient" # sudoedit creates a temporary file, and then overwrites # the target file with the edited copy. Note that option # "--no-wait" here would break this behavior. export SUDO_EDITOR="$HOME/emacs-current/bin/emacsclient"


 * Create or amend your desktop's launcher shortcut.
 * Under KDE, use: "$HOME/emacs-current/bin/emacs" %F The Emacs icon for that launcher shortcut is here: $HOME/emacs-current/share/icons/hicolor/scalable/apps
 * Under Windows, create a shortcut to runemacs.exe.
 * Configure double-click file opening.
 * Under the MATE Desktop, create a file named /home/ /.local/share/applications/OpenWithEmacs.desktop with the following contents:    #!/usr/bin/env xdg-open     [Desktop Entry]    Version=1.0    Type=Application    Terminal=false    Icon=/home/ /emacs-current/share/icons/hicolor/scalable/apps/emacs.svg    Exec=/home/ /emacs-current/bin/emacsclient --no-wait %F    Name=OpenWithEmacs    Hidden=false  You will then see an entry called "OpenWithEmacs" if you right-click on a file and choose "Open with..." on the pop-up menu. If you choose the "Other application..." menu entry, you will be able to set "OpenWithEmacs" as the default for that kind of file.
 * Under Xfce, use MenuLibre to add a launcher for: /home/ /emacs-current/bin/emacsclient --no-wait %F Then right-click on a file, select "Open with...", and associate the file type with that launcher.
 * Under KDE, use: /home/ /emacs-current/bin/emacsclient --no-wait In order to amend Dolphin's "Open With..." menu, open the Properties of a file which matches the type you want to edit, and then klick on "File Type Options".
 * Under Windows, associate text files with emacsclientw.exe and set or amend user environment variable ALTERNATE_EDITOR to the full path of executable runemacs.exe . Then start a tool like FileTypesMan from NirSoft, search for emacsclientw.exe, and add argument --no-wait before parameter "%1". (untested) Alternatively, use the following commands: ftype emacs-file=c:\emacs-26.2\bin\emacsclientw.exe --no-wait "%1"  assoc .txt=emacs-file If Emacs is already running, double-clicking on files with Unicode characters on their path will not work, those characters will get garbled inside Emacs. If you know how to fix or work-around this issue, please drop me a line.
 * If you autostart Emacs, adjust the path to Emacs there too.
 * If you have any other scripts that have a hard-coded path to emacs or emacsclient, adjust them too. For example, I have a pipe-to-emacs-server.sh script on my system, so that I can comfortably redirect console output to Emacs.
 * Make sure that your desktop environment (like KDE) is not eating some of your favourite key combinations (like Ctrl+F2) for its own functions like virtual desktop support. Otherwise, Emacs will not get to see them at all.
 * Fix rgrep under Windows by customizing grep-find-template (in customize group grep). If you have Cygwin installed, this works for me:

C:\cygwin64\bin\find.  -type f  -exec /usr/bin/grep  --regexp= --with-filename --line-number --color=always {} +


 * Notes about rgrep above:
 * Setting this variable is hard, because Emacs will run it as a Windows program, but find and grep expect the Unix escaping rules and so on.
 * Executable path "C:\cygwin64\bin\find" works even if Cygwin is not on your PATH.
 * Executable path "/usr/bin/grep" must be in Unix/Cygwin format, because find is a Cygwin executable.
 * The template does not need the base dir variable  because Emacs changes to this directory before running find, so omitting  prevents encoding issues if the directory name contains international characters like 'é'.
 * The "+" and the end, rather than the usual ";", makes find behave like xargs, so the whole operation runs much faster.
 * Instead of specifying "--color=always" in the template, you could customizing "Grep Highlight Matches" to "Use --color=always", but that yields many warnings like "/usr/bin/grep: warning: GREP_OPTIONS is deprecated; please use an alias or script". This issue has been fixed in the upcoming Emacs version 25.
 * You probably want to customize "Match face" to something other than yellow, which is the colour normally used for manually-highlighted text. Colour "pale green" does the trick for me.

= Building from source under Linux =


 * Download and unpack:

wget http://ftp.gnu.org/gnu/emacs/emacs-27.1.tar.gz tar -xzf emacs-27.1.tar.gz  cd emacs-27.1


 * Install dependencies. This works under Ubuntu:

sudo apt-get install build-essential sudo apt-get build-dep emacs25  # You need to enable source packages first.
 * 1) Satisfy most dependencies automatically.


 * Apparently that does not satisfy the Xaw3d dependency:

Does Emacs use -lXaw3d? no
 * But I do not actually know what type of scroll bar or whatever that Xaw3d package is. If you know more, please drop me a line.


 * If you want Emacs to use libsystemd, you will need Ubuntu/Debian package libsystemd-dev.


 * If you want --with-xwidgets, you will need Ubuntu/Debian package libwebkit2gtk-4.0-dev.


 * Stable support for Cairo drawing is only available from Emacs version 27.1, so you should probably refrain from using --with-cairo with older versions. According to the mailing list, an Emacs built with --with-cairo doesn't need xft, so you can ignore configuration message "Does Emacs use -lxft? no".


 * If you want Emacs to use the JSON library Jansson (from Emacs 27), you will need Ubuntu/Debian package libjansson-dev.


 * Configure:

./configure CFLAGS="-g3 -O3 -march=native -flto"  --with-x-toolkit=gtk3  --with-cairo  --with-xwidgets  --prefix="$HOME/emacs-27.1-bin"


 * The standard CFLAGS are "-g3 -O2", but you want maximum performance.


 * Now you can take a look at the configuration table at the end of the configuration log and see if everything looks alright.


 * Build and install:

make --output-sync=recurse -j "$(( $(getconf _NPROCESSORS_ONLN) + 1 ))"  &&  make install-strip

= Unresolved issues =

If know how to fix or work-around any of these issues, please drop me a line.


 * When configuring the build, see unsatisfied dependency "Xaw3d" above.
 * Under Windows, emacsclientw.exe does not pass Unicode characters in file paths correctly to an already-running Emacs instance.