001: @c This is part of the Emacs manual.
002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software
003: @c Foundation, Inc.
004: @c See file emacs.texi for copying conditions.
005: @node Packages
006: @chapter Emacs Lisp Packages
007: @cindex Package
008: @cindex Emacs Lisp package archive
009: @cindex Package archive
010: 
011: Emacs includes a facility that lets you easily download and install
012: @dfn{packages} that implement additional features.  Each package is a
013: separate Emacs Lisp program, sometimes including other components such
014: as an Info manual.
015: 
016:   @kbd{M-x list-packages} brings up a buffer named @file{*Packages*}
017: with a list of all packages.  You can install or uninstall packages
018: via this buffer.  @xref{Package Menu}.
019: 
020:   The command @kbd{C-h P} (@code{describe-package}) prompts for the
021: name of a package, and displays a help buffer describing the
022: attributes of the package and the features that it implements.
023: 
024:   By default, Emacs downloads packages from a @dfn{package archive}
025: maintained by the Emacs developers and hosted by the GNU project.
026: Optionally, you can also download packages from archives maintained by
027: third parties.  @xref{Package Installation}.
028: 
029:   For information about turning an Emacs Lisp program into an
030: installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference
031: Manual}.
032: 
033: @menu
034: * Package Menu::         Buffer for viewing and managing packages.
035: * Package Installation:: Options for package installation.
036: * Package Files::        Where packages are installed.
037: @end menu
038: 
039: @node Package Menu
040: @section The Package Menu Buffer
041: @cindex package menu
042: @cindex built-in package
043: @findex list-packages
044: 
045: The command @kbd{M-x list-packages} brings up the @dfn{package menu}.
046: This is a buffer listing all the packages that Emacs knows about, one
047: on each line, with the following information:
048: 
049: @itemize @bullet
050: @item
051: The package name (e.g., @samp{auctex}).
052: 
053: @item
054: The package's version number (e.g., @samp{11.86}).
055: 
056: @item
057: The package's status---normally one of @samp{available} (can be
058: downloaded from the package archive), @samp{installed},
059: @c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
060: or @samp{built-in} (included in Emacs by default).  The status
061: @samp{external} means the package is not built-in and not from the
062: directory specified by @code{package-user-dir} (@pxref{Package
063: Files}).  External packages are treated much like built-in: they
064: cannot be deleted through the package menu, and are not considered for
065: upgrading.
066: 
067: The status can also be @samp{new}.  This is equivalent to
068: @samp{available}, except that it means the package became newly
069: available on the package archive after your last invocation of
070: @kbd{M-x list-packages}.  In other instances, a package may have the
071: status @samp{held}, @samp{disabled}, or @samp{obsolete}.
072: @xref{Package Installation}.
073: 
074: @item
075: A short description of the package.
076: @end itemize
077: 
078: @noindent
079: The @code{list-packages} command accesses the network, to retrieve the
080: list of available packages from package archive servers.  If the
081: network is unavailable, it falls back on the most recently retrieved
082: list.
083: 
084: The following commands are available in the package menu:
085: 
086: @table @kbd
087: @item h
088: Print a short message summarizing how to use the package menu
089: (@code{package-menu-quick-help}).
090: 
091: @item ?
092: @itemx @key{RET}
093: Display a help buffer for the package on the current line
094: (@code{package-menu-describe-package}), similar to the help window
095: displayed by the @kbd{C-h P} command (@pxref{Packages}).
096: 
097: @item i
098: Mark the package on the current line for installation
099: (@code{package-menu-mark-install}).  If the package status is
100: @samp{available}, this adds an @samp{I} character to the start of the
101: line; typing @kbd{x} (see below) will download and install the
102: package.
103: 
104: @item d
105: Mark the package on the current line for deletion
106: (@code{package-menu-mark-delete}).  If the package status is
107: @samp{installed}, this adds a @samp{D} character to the start of the
108: line; typing @kbd{x} (see below) will delete the package.
109: @xref{Package Files}, for information about what package deletion
110: entails.
111: 
112: @item ~
113: Mark all obsolete packages for deletion
114: (@code{package-menu-mark-obsolete-for-deletion}).  This marks for
115: deletion all the packages whose status is @samp{obsolete}.
116: 
117: @item u
118: @itemx @key{DEL}
119: Remove any installation or deletion mark previously added to the
120: current line by an @kbd{i} or @kbd{d} command.
121: 
122: @item U
123: Mark all package with a newer available version for upgrading
124: (@code{package-menu-mark-upgrades}).  This places an installation mark
125: on the new available versions, and a deletion mark on the old
126: installed versions.
127: 
128: @item x
129: @vindex package-menu-async
130: Download and install all packages marked with @kbd{i}, and their
131: dependencies; also, delete all packages marked with @kbd{d}
132: (@code{package-menu-execute}).  This also removes the marks.
133: 
134: @item r
135: Refresh the package list (@code{package-menu-refresh}).  This fetches
136: the list of available packages from the package archive again, and
137: recomputes the package list.
138: 
139: @item f
140: Filter the package list (@code{package-menu-filter}).  This prompts
141: for a keyword (e.g., @samp{games}), then shows only the packages
142: that relate to that keyword.  To restore the full package list,
143: type @kbd{q}.
144: 
145: @item H
146: Permanently hide packages that match a regexp
147: (@code{package-menu-hide-package}).
148: 
149: @item (
150: Toggle visibility of old versions of packages and also of versions
151: from lower-priority archives (@code{package-menu-toggle-hiding}).
152: @end table
153: 
154: @noindent
155: For example, you can install a package by typing @kbd{i} on the line
156: listing that package, followed by @kbd{x}.
157: 
158: @node Package Installation
159: @section Package Installation
160: 
161: @findex package-install
162:   Packages are most conveniently installed using the package menu
163: (@pxref{Package Menu}), but you can also use the command @kbd{M-x
164: package-install}.  This prompts for the name of a package with the
165: @samp{available} status, then downloads and installs it.
166: 
167: @cindex package requirements
168:   A package may @dfn{require} certain other packages to be installed,
169: because it relies on functionality provided by them.  When Emacs
170: installs such a package, it also automatically downloads and installs
171: any required package that is not already installed.  (If a required
172: package is somehow unavailable, Emacs signals an error and stops
173: installation.)  A package's requirements list is shown in its help
174: buffer.
175: 
176: @vindex package-archives
177:   By default, packages are downloaded from a single package archive
178: maintained by the Emacs developers.  This is controlled by the
179: variable @code{package-archives}, whose value is a list of package
180: archives known to Emacs.  Each list element must have the form
181: @code{(@var{id} . @var{location})}, where @var{id} is the name of a
182: package archive and @var{location} is the @acronym{HTTP} address or
183: name of the package archive directory.  You can alter this list if you
184: wish to use third party package archives---but do so at your own risk,
185: and use only third parties that you think you can trust!
186: 
187: @anchor{Package Signing}
188: @cindex package security
189: @cindex package signing
190:   The maintainers of package archives can increase the trust that you
191: can have in their packages by @dfn{signing} them.  They generate a
192: private/public pair of cryptographic keys, and use the private key to
193: create a @dfn{signature file} for each package.  With the public key, you
194: can use the signature files to verify the package creator and make sure
195: the package has not been tampered with.  Signature verification uses
196: @uref{https://www.gnupg.org/, the GnuPG package} via the EasyPG
197: interface (@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}).
198: A valid signature is not a cast-iron
199: guarantee that a package is not malicious, so you should still
200: exercise caution.  Package archives should provide instructions
201: on how you can obtain their public key.  One way is to download the
202: key from a server such as @url{https://pgp.mit.edu/}.
203: Use @kbd{M-x package-import-keyring} to import the key into Emacs.
204: Emacs stores package keys in the directory specified by the variable
205: @code{package-gnupghome-dir}, by default in the @file{gnupg}
206: subdirectory of @code{package-user-dir}, which causes Emacs to invoke
207: GnuPG with the option @samp{--homedir} when verifying signatures.
208: If @code{package-gnupghome-dir} is @code{nil}, GnuPG's option
209: @samp{--homedir} is omitted.
210: The public key for the GNU package archive is distributed with Emacs,
211: in the @file{etc/package-keyring.gpg}.  Emacs uses it automatically.
212: 
213: @vindex package-check-signature
214: @vindex package-unsigned-archives
215:   If the user option @code{package-check-signature} is non-@code{nil},
216: Emacs attempts to verify signatures when you install packages.  If the
217: option has the value @code{allow-unsigned}, you can still install a
218: package that is not signed.  If you use some archives that do not sign
219: their packages, you can add them to the list @code{package-unsigned-archives}.
220: 
221:   For more information on cryptographic keys and signing,
222: @pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}.
223: Emacs comes with an interface to GNU Privacy Guard,
224: @pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}.
225: 
226: @vindex package-pinned-packages
227:   If you have more than one package archive enabled, and some of them
228: offer different versions of the same package, you may find the option
229: @code{package-pinned-packages} useful.  You can add package/archive
230: pairs to this list, to ensure that the specified package is only ever
231: downloaded from the specified archive.
232: 
233: @vindex package-archive-priorities
234: @vindex package-menu-hide-low-priority
235:   Another option that is useful when you have several package archives
236: enabled is @code{package-archive-priorities}.  It specifies the
237: priority of each archive (higher numbers specify higher priority
238: archives).  By default, archives have the priority of zero, unless
239: specified otherwise by this option's value.  Packages from
240: lower-priority archives will not be shown in the menu, if the same
241: package is available from a higher-priority archive.  (This is
242: controlled by the value of @code{package-menu-hide-low-priority}.)
243: 
244:   Once a package is downloaded and installed, it is made available to
245: the current Emacs session.  Making a package available adds its
246: directory to @code{load-path} and loads its autoloads.  The effect of
247: a package's autoloads varies from package to package.  Most packages
248: just make some new commands available, while others have more
249: wide-ranging effects on the Emacs session.  For such information,
250: consult the package's help buffer.
251: 
252:   After a package is installed, it is automatically made available by
253: Emacs in all subsequent sessions.  This happens at startup, before
254: processing the init file but after processing the early init file
255: (@pxref{Early Init File}).  As an exception, Emacs does not make
256: packages available at startup if invoked with the @samp{-q} or
257: @samp{--no-init-file} options (@pxref{Initial Options}).
258: 
259: @vindex package-enable-at-startup
260:   To keep Emacs from automatically making packages available at
261: startup, change the variable @code{package-enable-at-startup} to
262: @code{nil}.  You must do this in the early init file, as the variable
263: is read before loading the regular init file.  Currently this variable
264: cannot be set via Customize.
265: 
266: @findex package-activate-all
267:   If you have set @code{package-enable-at-startup} to @code{nil}, you
268: can still make packages available either during or after startup.  To
269: make installed packages available during startup, call the function
270: @code{package-activate-all} in your init file.  To make installed
271: packages available after startup, invoke the command @kbd{M-:
272: (package-activate-all) RET}.
273: 
274: @vindex package-load-list
275:   For finer control over which packages are made available at startup,
276: you can use the variable @code{package-load-list}.  Its value should
277: be a list.  A list element of the form @w{@code{(@var{name}
278: @var{version})}} tells Emacs to make available version @var{version} of
279: the package named @var{name}.  Here, @var{version} should be a version
280: string (corresponding to a specific version of the package), or
281: @code{t} (which means to make available any installed version), or
282: @code{nil} (which means no version; this disables the package,
283: preventing it from being made available).  A list element can also be
284: the symbol @code{all}, which means to make available the latest
285: installed version of any package not named by the other list elements.
286: The default value is just @code{'(all)}.
287: 
288:   For example, if you set @code{package-load-list} to @w{@code{'((muse
289: "3.20") all)}}, then Emacs only makes available version 3.20 of the
290: @samp{muse} package, plus any installed version of packages other than
291: @samp{muse}.  Any other version of @samp{muse} that happens to be
292: installed will be ignored.  The @samp{muse} package will be listed in
293: the package menu with the @samp{held} status.
294: 
295: @node Package Files
296: @section Package Files and Directory Layout
297: @cindex package directory
298: 
299: @cindex package file
300: @findex package-install-file
301:   Each package is downloaded from the package archive in the form of a
302: single @dfn{package file}---either an Emacs Lisp source file, or a tar
303: file containing multiple Emacs Lisp source and other files.  Package
304: files are automatically retrieved, processed, and disposed of by the
305: Emacs commands that install packages.  Normally, you will not need to
306: deal directly with them, unless you are making a package
307: (@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}).  Should
308: you ever need to install a package directly from a package file, use
309: the command @kbd{M-x package-install-file}.
310: 
311: @vindex package-user-dir
312:   Once installed, the contents of a package are placed in a
313: subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of
314: that directory by changing the variable @code{package-user-dir}).  The
315: package subdirectory is named @file{@var{name}-@var{version}}, where
316: @var{name} is the package name and @var{version} is its version
317: string.
318: 
319: @cindex system-wide packages
320: @vindex package-directory-list
321:   In addition to @code{package-user-dir}, Emacs looks for installed
322: packages in the directories listed in @code{package-directory-list}.
323: These directories are meant for system administrators to make Emacs
324: packages available system-wide; Emacs itself never installs packages
325: there.  The package subdirectories for @code{package-directory-list}
326: are laid out in the same way as in @code{package-user-dir}.
327: 
328:   Deleting a package (@pxref{Package Menu}) involves deleting the
329: corresponding package subdirectory.  This only works for packages
330: installed in @code{package-user-dir}; if told to act on a package in a
331: system-wide package directory, the deletion command signals an error.
332: