procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add conditional loading examples to use-package manual

Browse source 
* doc/misc/use-package.texi (Conditional loading): Expand section with
examples.

Resolves https://github.com/jwiegley/use-package/issues/693
This commit is contained in:
Stefan Kangas 2022-12-09 04:15:32 +01:00
parent 67ef92fb0e
commit a17a6036dd
1 changed files with 45 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

51
doc/misc/use-package.texi
View file

@ -394,22 +394,61 @@ is provided as an alias for @code{:if}. Finally, the @code{:unless}
keyword is the inverse of @code{:if}, such that @w{@code{:unless foo}} keyword is the inverse of @code{:if}, such that @w{@code{:unless foo}}
means the same thing as @w{@code{:if (not foo)}}. means the same thing as @w{@code{:if (not foo)}}.
For example, if you only want @samp{foo} in graphical Emacs sessions, For example, if you only want to load @samp{foo} in graphical Emacs
you could use the following: sessions, you could use the following:
@lisp @lisp
(use-package foo (use-package foo
:if (display-graphic-p)) :if (display-graphic-p))
@end lisp @end lisp
Another common use case is to make it conditional on the operating @subheading Some common use cases
system:
Here are some common cases for conditional loading, and how to achieve
them.
@itemize
@item Operating system
This example loads a package only on GNU/Linux. See the
@code{system-type} docstring for other valid values.
@lisp @lisp
(use-package foo :if (eq system-type 'gnu/linux)
:if (memq window-system '(mac ns)))
@end lisp @end lisp
@item Window system
This example loads a package only on macOS and X. See the
@code{window-system} docstring for valid values.
@lisp
:if (memq window-system '(ns x))
@end lisp
@item Installed package
This example loads a package only when the @samp{foo} package is
installed.
@lisp
:if (package-installed-p 'foo)
@end lisp
@item Libraries in @code{load-path}
This example loads a package only when @file{foo.el} is available in
your @code{load-path} (for example, if you installed that file
manually):
@lisp
:if (locate-library "foo.el")
@end lisp
@end itemize
@subheading Making conditional loading affect @code{:preface} and @code{:ensure}
@cindex conditional loading before @code{:preface} or @code{:ensure} @cindex conditional loading before @code{:preface} or @code{:ensure}
If you need to conditionalize a use-package form so that the condition If you need to conditionalize a use-package form so that the condition
occurs before even @code{:ensure} or @code{:preface}, use @code{when} occurs before even @code{:ensure} or @code{:preface}, use @code{when}