From e702cbac4ee74b198df598d78a91f9b7845ba88b Mon Sep 17 00:00:00 2001 From: Daniel Nicolai Date: Tue, 16 Mar 2021 22:31:39 +0100 Subject: [PATCH] Add to docs, replacing a layer package with a local version When contributing to packages it is often handy to replace a package, already installed and configured by some layer with a local version of the package (i.e. a git repo). This commit adds instructions for how to achieve that. --- doc/DOCUMENTATION.org | 4 ++++ doc/FAQ.org | 22 ++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/doc/DOCUMENTATION.org b/doc/DOCUMENTATION.org index 5db3b90a7..a1b0c34e7 100644 --- a/doc/DOCUMENTATION.org +++ b/doc/DOCUMENTATION.org @@ -23,6 +23,7 @@ - [[#declaration][Declaration]] - [[#initialization][Initialization]] - [[#exclusion][Exclusion]] + - [[#overriding-a-layer-package][Overriding a layer package]] - [[#without-a-layer][Without a layer]] - [[#packages-synchronization][Packages synchronization]] - [[#types-of-configuration-layers][Types of configuration layers]] @@ -435,6 +436,9 @@ Example: (setq -excluded-packages '(package1 package2 ...) #+END_SRC +**** Overriding a layer package + See [[https://www.spacemacs.org/doc/FAQ.html#how-to-override-a-layer-package][this answer in the FAQ's]]. + *** Without a layer Sometimes a layer can be an unnecessary overhead, this is the case if you just want to install a package with very few configuration associated to it. A good diff --git a/doc/FAQ.org b/doc/FAQ.org index c82ae7bfd..a5749deb7 100644 --- a/doc/FAQ.org +++ b/doc/FAQ.org @@ -28,6 +28,7 @@ - [[#i-want-to-learn-elisp-where-do-i-start-][I want to learn elisp, where do I start ?]] - [[#how-do-i][How do I]] - [[#install-a-package-not-provided-by-a-layer][Install a package not provided by a layer?]] + - [[#how-to-override-a-layer-package][How to override a layer package?]] - [[#disable-a-package-completely][Disable a package completely?]] - [[#disable-a-package-only-for-a-specific-major-mode][Disable a package only for a specific major-mode?]] - [[#disable-company-for-a-specific-major-mode][Disable company for a specific major-mode?]] @@ -287,6 +288,27 @@ Spacemacs provides a variable in the =dotspacemacs/layers= function in to the list and it will be installed when you reload your configuration with ~SPC f e R~, or at the next Spacemacs launch. +** How to override a layer package? + To replace a package that is installed and configured by a layer, without + losing the layer's configuration for that package, add the package to your + =dotspacemacs-additional-packages= with the =:location= keyword set to the + value =local=: + #+begin_src emacs-lisp :tangle yes + (package-name :location local) + #+end_src + The package should reside at =/local//= (this could be a + symbolic link to the real package (repo) directory). The package will still + get configured (but not loaded) by the layer. To load the package, require it + from your =dotspacemacs/user-config=: =(require 'package-name)=. In this way + you can easily switch between the custom version and the version configured by + the layer by commenting in/out the line in =dotspacemacs-additional-packages= + (to restore deferred loading also comment out the =require= form in + =dotspacemacs/user-config=). + + You could also fully replace (i.e. overwrite) the layer version of the package + by using a Quelpa recipe with the pseudo-fetcher =local= as described [[https://develop.spacemacs.org/doc/LAYERS.html#packagesel][here]] and + [[https://github.com/quelpa/quelpa#file][here]]. + ** Disable a package completely? To completely disable a package and effectively uninstalling it even if it is part of your used layers, look for the variable =dotspacemacs-excluded-packages=