package.texi 14.2 KB
Newer Older
1
@c This is part of the Emacs manual.
Paul Eggert's avatar
Paul Eggert committed
2
@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software
3
@c Foundation, Inc.
4 5 6 7 8 9 10 11 12 13 14 15 16
@c See file emacs.texi for copying conditions.
@node Packages
@chapter Emacs Lisp Packages
@cindex Package
@cindex Emacs Lisp package archive
@cindex Package archive
@cindex Emacs Lisp package

Emacs includes a facility that lets you easily download and install
@dfn{packages} that implement additional features.  Each package is a
separate Emacs Lisp program, sometimes including other components such
as an Info manual.

17
  @kbd{M-x list-packages} brings up a buffer named @file{*Packages*}
18 19 20 21 22
with a list of all packages.  You can install or uninstall packages
via this buffer.  @xref{Package Menu}.

@findex describe-package
  The command @kbd{C-h P} (@code{describe-package}) prompts for the
23
name of a package, and displays a help buffer describing the
24 25 26 27 28 29 30 31 32
attributes of the package and the features that it implements.

  By default, Emacs downloads packages from a @dfn{package archive}
maintained by the Emacs developers and hosted by the GNU project.
Optionally, you can also download packages from archives maintained by
third parties.  @xref{Package Installation}.

  For information about turning an Emacs Lisp program into an
installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference
33
Manual}.
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

@menu
* Package Menu::         Buffer for viewing and managing packages.
* Package Installation:: Options for package installation.
* Package Files::        Where packages are installed.
@end menu

@node Package Menu
@section The Package Menu Buffer
@cindex package menu
@cindex built-in package
@findex list-packages

The command @kbd{M-x list-packages} brings up the @dfn{package menu}.
This is a buffer listing all the packages that Emacs knows about, one
on each line, with the following information:

@itemize @bullet
@item
53
The package name (e.g., @samp{auctex}).
54 55

@item
56
The package's version number (e.g., @samp{11.86}).
57 58 59

@item
The package's status---normally one of @samp{available} (can be
60
downloaded from the package archive), @samp{installed},
61
@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
62 63 64 65 66 67
or @samp{built-in} (included in Emacs by default).  The status
@samp{external} means the package is not built-in and not from the
directory specified by @code{package-user-dir} (@pxref{Package
Files}).  External packages are treated much like built-in: they
cannot be deleted through the package menu, and are not considered for
upgrading.
68

69 70 71 72 73 74
The status can also be @samp{new}.  This is equivalent to
@samp{available}, except that it means the package became newly
available on the package archive after your last invocation of
@kbd{M-x list-packages}.  In other instances, a package may have the
status @samp{held}, @samp{disabled}, or @samp{obsolete}.
@xref{Package Installation}.
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113

@item
A short description of the package.
@end itemize

@noindent
The @code{list-packages} command accesses the network, to retrieve the
list of available packages from the package archive server.  If the
network is unavailable, it falls back on the most recently retrieved
list.

The following commands are available in the package menu:

@table @kbd
@item h
Print a short message summarizing how to use the package menu
(@code{package-menu-quick-help}).

@item ?
@itemx @key{RET}
Display a help buffer for the package on the current line
(@code{package-menu-describe-package}), similar to the help window
displayed by the @kbd{C-h P} command (@pxref{Packages}).

@item i
Mark the package on the current line for installation
(@code{package-menu-mark-install}).  If the package status is
@samp{available}, this adds an @samp{I} character to the start of the
line; typing @kbd{x} (see below) will download and install the
package.

@item d
Mark the package on the current line for deletion
(@code{package-menu-mark-delete}).  If the package status is
@samp{installed}, this adds a @samp{D} character to the start of the
line; typing @kbd{x} (see below) will delete the package.
@xref{Package Files}, for information about what package deletion
entails.

114 115 116 117 118
@item ~
Mark all obsolete packages for deletion
(@code{package-menu-mark-obsolete-for-deletion}).  This marks for
deletion all the packages whose status is @samp{obsolete}.

119
@item u
120
@itemx @key{DEL}
121 122 123
Remove any installation or deletion mark previously added to the
current line by an @kbd{i} or @kbd{d} command.

124
@item U
Paul Eggert's avatar
Paul Eggert committed
125
Mark all package with a newer available version for upgrading
126 127 128 129
(@code{package-menu-mark-upgrades}).  This places an installation mark
on the new available versions, and a deletion mark on the old
installed versions.

130
@item x
131
@vindex package-menu-async
132 133 134 135 136
Download and install all packages marked with @kbd{i}, and their
dependencies; also, delete all packages marked with @kbd{d}
(@code{package-menu-execute}).  This also removes the marks.

@item r
137 138 139
Refresh the package list (@code{package-menu-refresh}).  This fetches
the list of available packages from the package archive again, and
recomputes the package list.
Glenn Morris's avatar
Glenn Morris committed
140 141 142 143 144 145

@item f
Filter the package list (@code{package-menu-filter}).  This prompts
for a keyword (e.g., @samp{games}), then shows only the packages
that relate to that keyword.  To restore the full package list,
type @kbd{q}.
146 147 148 149 150 151 152 153

@item H
Permanently hide packages that match a regexp
(@code{package-menu-hide-package}).

@item (
Toggle visibility of old versions of packages and also of versions
from lower-priority archives (@code{package-menu-toggle-hiding}).
154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
@end table

@noindent
For example, you can install a package by typing @kbd{i} on the line
listing that package, followed by @kbd{x}.

@node Package Installation
@section Package Installation

@findex package-install
  Packages are most conveniently installed using the package menu
(@pxref{Package Menu}), but you can also use the command @kbd{M-x
package-install}.  This prompts for the name of a package with the
@samp{available} status, then downloads and installs it.

@cindex package requirements
  A package may @dfn{require} certain other packages to be installed,
because it relies on functionality provided by them.  When Emacs
installs such a package, it also automatically downloads and installs
any required package that is not already installed.  (If a required
package is somehow unavailable, Emacs signals an error and stops
installation.)  A package's requirements list is shown in its help
buffer.

@vindex package-archives
  By default, packages are downloaded from a single package archive
maintained by the Emacs developers.  This is controlled by the
variable @code{package-archives}, whose value is a list of package
archives known to Emacs.  Each list element must have the form
@code{(@var{id} . @var{location})}, where @var{id} is the name of a
package archive and @var{location} is the @acronym{HTTP} address or
directory name of the package archive.  You can alter this list if you
wish to use third party package archives---but do so at your own risk,
and use only third parties that you think you can trust!

189 190 191 192 193
@anchor{Package Signing}
@cindex package security
@cindex package signing
  The maintainers of package archives can increase the trust that you
can have in their packages by @dfn{signing} them.  They generate a
Paul Eggert's avatar
Paul Eggert committed
194
private/public pair of cryptographic keys, and use the private key to
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
create a @dfn{signature file} for each package.  With the public key, you
can use the signature files to verify who created the package, and
that it has not been modified.  A valid signature is not a cast-iron
guarantee that a package is not malicious, so you should still
exercise caution.  Package archives should provide instructions
on how you can obtain their public key.  One way is to download the
key from a server such as @url{http://pgp.mit.edu/}.
Use @kbd{M-x package-import-keyring} to import the key into Emacs.
Emacs stores package keys in the @file{gnupg} subdirectory
of @code{package-user-dir}.
The public key for the GNU package archive is distributed with Emacs,
in the @file{etc/package-keyring.gpg}.  Emacs uses it automatically.

@vindex package-check-signature
@vindex package-unsigned-archives
  If the user option @code{package-check-signature} is non-@code{nil},
Emacs attempts to verify signatures when you install packages.  If the
option has the value @code{allow-unsigned}, you can still install a
package that is not signed.  If you use some archives that do not sign
their packages, you can add them to the list @code{package-unsigned-archives}.

Paul Eggert's avatar
Paul Eggert committed
216
  For more information on cryptographic keys and signing,
217 218 219 220
@pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}.
Emacs comes with an interface to GNU Privacy Guard,
@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}.

221 222 223 224 225 226 227
@vindex package-pinned-packages
  If you have more than one package archive enabled, and some of them
offer different versions of the same package, you may find the option
@code{package-pinned-packages} useful.  You can add package/archive
pairs to this list, to ensure that the specified package is only ever
downloaded from the specified archive.

228 229 230 231 232 233 234 235 236 237 238
@vindex package-archive-priorities
@vindex package-menu-hide-low-priority
  Another option that is useful when you have several package archives
enabled is @code{package-archive-priorities}.  It specifies the
priority of each archive (higher numbers specify higher priority
archives).  By default, archives have the priority of zero, unless
specified otherwise by this option's value.  Packages from
lower-priority archives will not be shown in the menu, if the same
package is available from a higher-priority archive.  (This is
controlled by the value of @code{package-menu-hide-low-priority}.)

Chong Yidong's avatar
Chong Yidong committed
239 240
  Once a package is downloaded and installed, it is @dfn{loaded} into
the current Emacs session.  Loading a package is not quite the same as
241 242 243 244 245 246
loading a Lisp library (@pxref{Lisp Libraries}); loading a package
adds its directory to @code{load-path} and loads its autoloads.  The
effect of a package's autoloads varies from package to package.  Most
packages just make some new commands available, while others have more
wide-ranging effects on the Emacs session.  For such information,
consult the package's help buffer.
Chong Yidong's avatar
Chong Yidong committed
247 248 249 250 251 252

  By default, Emacs also automatically loads all installed packages in
subsequent Emacs sessions.  This happens at startup, after processing
the init file (@pxref{Init File}).  As an exception, Emacs does not
load packages at startup if invoked with the @samp{-q} or
@samp{--no-init-file} options (@pxref{Initial Options}).
253 254 255

@vindex package-enable-at-startup
  To disable automatic package loading, change the variable
Chong Yidong's avatar
Chong Yidong committed
256 257 258 259 260 261 262 263 264 265 266 267
@code{package-enable-at-startup} to @code{nil}.

@findex package-initialize
  The reason automatic package loading occurs after loading the init
file is that user options only receive their customized values after
loading the init file, including user options which affect the
packaging system.  In some circumstances, you may want to load
packages explicitly in your init file (usually because some other code
in your init file depends on a package).  In that case, your init file
should call the function @code{package-initialize}.  It is up to you
to ensure that relevant user options, such as @code{package-load-list}
(see below), are set up prior to the @code{package-initialize} call.
268
This will automatically set @code{package-enable-at-startup} to @code{nil}, to
Chong Yidong's avatar
Chong Yidong committed
269 270 271 272
avoid loading the packages again after processing the init file.
Alternatively, you may choose to completely inhibit package loading at
startup, and invoke the command @kbd{M-x package-initialize} to load
your packages manually.
273 274 275 276 277 278 279 280 281

@vindex package-load-list
  For finer control over package loading, you can use the variable
@code{package-load-list}.  Its value should be a list.  A list element
of the form @code{(@var{name} @var{version})} tells Emacs to load
version @var{version} of the package named @var{name}.  Here,
@var{version} should be a version string (corresponding to a specific
version of the package), or @code{t} (which means to load any
installed version), or @code{nil} (which means no version; this
Paul Eggert's avatar
Paul Eggert committed
282
disables the package, preventing it from being loaded).  A list
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
element can also be the symbol @code{all}, which means to load the
latest installed version of any package not named by the other list
elements.  The default value is just @code{'(all)}.

  For example, if you set @code{package-load-list} to @code{'((muse
"3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse}
package, plus any installed version of packages other than
@samp{muse}.  Any other version of @samp{muse} that happens to be
installed will be ignored.  The @samp{muse} package will be listed in
the package menu with the @samp{held} status.

@node Package Files
@section Package Files and Directory Layout
@cindex package directory

@cindex package file
@findex package-install-file
  Each package is downloaded from the package archive in the form of a
single @dfn{package file}---either an Emacs Lisp source file, or a tar
file containing multiple Emacs Lisp source and other files.  Package
files are automatically retrieved, processed, and disposed of by the
Emacs commands that install packages.  Normally, you will not need to
deal directly with them, unless you are making a package
(@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}).  Should
you ever need to install a package directly from a package file, use
the command @kbd{M-x package-install-file}.

@vindex package-user-dir
  Once installed, the contents of a package are placed in a
subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of
that directory by changing the variable @code{package-user-dir}).  The
package subdirectory is named @file{@var{name}-@var{version}}, where
@var{name} is the package name and @var{version} is its version
string.

@cindex system-wide packages
@vindex package-directory-list
  In addition to @code{package-user-dir}, Emacs looks for installed
packages in the directories listed in @code{package-directory-list}.
These directories are meant for system administrators to make Emacs
packages available system-wide; Emacs itself never installs packages
there.  The package subdirectories for @code{package-directory-list}
are laid out in the same way as in @code{package-user-dir}.

  Deleting a package (@pxref{Package Menu}) involves deleting the
corresponding package subdirectory.  This only works for packages
installed in @code{package-user-dir}; if told to act on a package in a
system-wide package directory, the deletion command signals an error.