Skip to content

Latest commit

 

History

History
223 lines (174 loc) · 10.1 KB

upgrading-emacs.rst.txt

File metadata and controls

223 lines (174 loc) · 10.1 KB

How to recompile all Emacs Lisp files after updating Emacs to a different version

Home URL:https://github.com/pierre-rouleau/pel
Project:PEL -- Pragmatic Emacs Library
Ref:PEL How-to Tips
Created:Saturday, March 1 2025.
Author: Pierre Rouleau <[email protected]>
Modified:2025-03-19 16:59:32 EDT, updated by Pierre Rouleau.
Copyright: © 2025, Pierre Rouleau

Table of Contents

1   Overview

This describes what you need to do once you have upgraded Emacs to a newer or older version.

It assumes that:

  1. You have installed a version of Emacs that is a different major version from the previous version of Emacs you were previously using. For example, you update Emacs 29.4 to 30.1 or from Emacs 29.1 to 28.1.
  2. You were already using PEL and have followed PEL installation procedure.
  3. PEL/Emacs is currently configured for normal operation (as opposed to fast PEL/Emacs operation).
    • If your PEL/Emacs is currently configured for fast operation, change it to run under normal operation by executing the pel-setup-normal command.
  4. You have stored the Emacs Lisp packages inside the directories described in the following table.
     
. Mandatory Directories  
. ~/.emacs.d/elpa A symbolic link to ~/.emacs.d/elpa-complete
. ~/.emacs.d/elpa-complete Holds all Emacs Lisp packages that originate from GNU Elpa, or MELPA repositories.
. ~/.emacs.d/utils Holds Emacs Lisp files that do not originate from GNU Elpa, or MELPA repositories.
.    
. Optional - Used in dual environment  
. ~/.emacs.d/elpa-graphics A symbolic link to ~/.emacs.d/elpa-complete-graphics
. ~/.emacs.d/elpa-complete-graphics Holds GUI-specific packages that originate from GNU Elpa, or MELPA repositories, when PEL dual-environment is used.
. ~/.emacs.d/utils-graphics Holds GUI-specific Emacs Lisp files that do not originate from GNU Elpa, or MELPA repositories when PEL dual-environment is used.
.    
. Optional - Attic directories Directories where PEL stores Emacs Lisp files removed bu pel-cleanup
. ~/.emacs.d/elpa-attic Files removed from the ~/.emacs.d/elpa
. ~/.emacs.d/elpa-attic-graphics Files removed from the ~/.emacs.d/elpa-graphics
. ~/.emacs.d/utils-attic Files removed from the ~/.emacs.d/utils
. ~/.emacs.d/utils-attic-graphics Files removed from the ~/.emacs.d/utils-graphics
.    
. Optional - Tree Sitter Support  
. ~/.emacs.d/tree-sitter-lang-bin Directory holding the tree-sitter binary dynamic libraries installed by the tree-sitter package.
. ~/.emacs.d/libtree-sitter Directory holding symbolic links to the files inside the ~/.emacs.d/tree-sitter-lang-bin directory.
. ~/.emacs.d/tree-sitter-langs-bin Symbolic link to the tree-sitter Emacs package bin sub-directory. With PEL it should point to something like ~/.emacs.d/elpa-complete/tree-sitter-langs-20250206.19 where the tail end date corresponds to the package you installed. Remember to update this symbolic link when updating the tree-sitter package and when updating Emacs (since you're likely to get a new version of the tree-sitter package).

2   How to recompile all elisp files after changing Emacs Version

After upgrading Emacs you need to recompile all Emacs Lisp files that PEL has installed. With PEL this is quite simple.

This assumes Emacs is currently not running.

2.1   Step 1: Rebuild PEL itself

To rebuild all PEL Emacs Lisp file, change the current directory to the PEL directory and execute:

make clean all

2.2   Step 2: Rebuild ~/.emacs.d/utils

  • Rename ~/.emacs.d/utils to ~/.emacs.d/utils.old or anything you want.

    • I normally use a number that represents Emacs major version number and keep it around. This way I can always go back to the previous version of Emacs by renaming the directories later.

  • If you used them, copy benchmark-init-modes.el and benchmark-init.el from the old utils into the new one at ~/.emacs.d/.utils.

  • Run Emacs in terminal mode in a shell. Use the e script described in the document titled Using the Emacs daemon and clients. Do not edit any file. Just start it without any argument.

    • PEL will take over, detect that the utils Emacs Lisp files are missing, will download the latest versions available and will recompile them with the new Emacs version.
    • If any compilation error or warning is detected, please add a report as a bug in the PEL project. I will try to address those. Please identify the version of Emacs you run, and include the generate errors.
    • Exit Emacs.

    At this point all the Emacs Lips packages should be inside the utils directory. The latest version of these package will be in the utils directory. If you prefer to use the old one you were using previously, just take the file from the backup directory you created earlier.

2.3   Step 3 Rebuild elpa

Inside ~/.emacs.d/ check for the presence of elpa or elpa-complete.. If you have elpa-complete you should also have a symbolic link named elpa that points to it. This means you have used the PEL fast startup mechanism, otherwise you did not use it.

2.3.1   If you only have ~/.emacs.d/elpa

  • Rename /.emacs.d/elpa to something else, like /.emacs.d/elpa-.old
  • Create a new ~/.emacs.d/elpa.
  • Run Emacs in terminal mode in a shell. Do not edit any file. Just start it without any argument.
    • PEL will take over, detect missing elpa packages, will download and build them. This will take some time, depending on how many packages you are using as identified by the various pel-use-... user-options.
    • If any compilation error or warning is detected, please add a report as a bug in the PEL project. I will try to address those. Please identify the version of Emacs you run, and include the generate errors.
    • Exit Emacs.

2.3.2   If you have ~/.emacs.d/elpa-complete

  • Rename /.emacs.d/elpa-complete to something else, like /.emacs.d/elpa-complete.old
  • Create a new ~/.emacs.d/elpa-complete.
  • Verify the ~/.emacs.d/elpa symbolic link points to the new ~/.emacs.d/elpa-complete directory.
  • Run Emacs in terminal mode in a shell. Do not edit any file. Just start it without any argument.
    • PEL will take over, detect missing elpa packages, will download and build them. This will take some time, depending on how many packages you are using as identified by the various pel-use-... user-options.
    • If any compilation error or warning is detected, please add a report as a bug in the PEL project. I will try to address those. Please identify the version of Emacs you run, and include the generate errors.
    • Exit Emacs.

2.4   Step 4: Run Emacs in graphics mode.

  • Open a shell and run the ge script to start an instance of Emacs in graphics-mode.
    • PEL will take over and will download and compile the packages that are required for Emacs in Graphics mode.
    • Exit Emacs

2.5   Step 5: Update tree-sitter language symbolic link.

Ref:Using tree-sitter with Emacs and PEL
  • Check if the ~/.emacs.d/tree-sitter-langs-bin symbolic link points to the tree-sitter lang bin directory inside the elpa-complete directory.
    • If the link is invalid, update it to point to the proper location. Something like:
      • ~/.emacs.d/elpa-complete/tree-sitter-langs-20250206.19/bin, when you have used PEL fast startup, or
      • ~/.emacs.d/elpa/tree-sitter-langs-20250206.19/bin/ if you have not used PEL fast startup.

2.6   Optional Following Steps

At this point you may want to activate Emacs dual-mode and run it. If there is anything missing PEL will install it and re-compile it.