all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
blob 7aade39615e7bd1c15542fb370fa2eddf0e516cf 18685 bytes (raw)
name: doc/emacs/package.texi 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
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
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
 
@c This is part of the Emacs manual.
@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2020 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Packages
@chapter Emacs Lisp Packages
@cindex Package
@cindex Emacs Lisp package archive
@cindex Package archive
The traditional way to install an Emacs Lisp file is to either install
it in the Emacs Lisp @dfn{load path} or to add the path to the file to
the load path list.  @xref{Lisp Libraries}. Then, the user should
follow the instructions given by the code author.

  Emacs now 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.

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

  The command @kbd{C-h P} (@code{describe-package}) prompts for the
name of a package, and displays a help buffer describing the
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
Manual}.

@menu
* Package Menu::         Buffer for viewing and managing packages.
* Package Statuses::     Which statuses a package can have.
* 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
The package name (e.g., @samp{auctex}).

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

@item
The package's status---normally one of @samp{available} (can be
downloaded from the package archive), @samp{installed},
@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
or @samp{built-in} (included in Emacs by default).
@xref{Package Statuses}.

@item
Which package archive this package is from, if you have more than one
package archive enabled.

@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 package archive servers.  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
@kindex h @r{(Package Menu)}
@findex package-menu-quick-help
Print a short message summarizing how to use the package menu
(@code{package-menu-quick-help}).

@item ?
@itemx @key{RET}
@kindex ? @r{(Package Menu)}
@kindex RET @r{(Package Menu)}
@findex package-menu-describe-package
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
@kindex i @r{(Package Menu)}
@findex package-menu-mark-install
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
@kindex d @r{(Package Menu)}
@findex package-menu-mark-delete
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.

@item ~
@kindex ~ @r{(Package Menu)}
@findex package-menu-mark-obsolete-for-deletion
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}.

@item u
@itemx @key{DEL}
@kindex u @r{(Package Menu)}
@findex package-menu-mark-unmark
Remove any installation or deletion mark previously added to the
current line by an @kbd{i} or @kbd{d} command
(@code{package-menu-mark-unmark}).

@item U
@kindex U @r{(Package Menu)}
@findex package-menu-mark-upgrades
Mark all package with a newer available version for upgrading
(@code{package-menu-mark-upgrades}).  This places an installation mark
on the new available versions, and a deletion mark on the old
installed versions (marked with status @samp{obsolete}).

@item x
@kindex x @r{(Package Menu)}
@vindex package-menu-async
@findex package-menu-execute
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 g
@item r
@kindex g @r{(Package Menu)}
@kindex r @r{(Package Menu)}
Refresh the package list (@code{revert-buffer}).  This fetches the
list of available packages from the package archive again, and
redisplays the package list.

@item H
@kindex H @r{(Package Menu)}
@findex package-menu-hide-package
Hide packages whose names match a regexp
(@code{package-menu-hide-package}).  This prompts for a regexp, and
then hides the packages with matching names.  The default value of the
regexp will hide only the package whose name is at point, so just
pressing @key{RET} to the prompt will hide the current package.

@item (
@kindex ( @r{(Package Menu)}
@findex package-menu-toggle-hiding
Toggle visibility of old versions of packages and also of versions
from lower-priority archives (@code{package-menu-toggle-hiding}).

@item / a
@kindex / a @r{(Package Menu)}
@findex package-menu-filter-by-archive
Filter package list by archive (@code{package-menu-filter-by-archive}).
This prompts for a package archive (e.g., @samp{gnu}), then shows only
packages from that archive.

@item / k
@kindex / k @r{(Package Menu)}
@findex package-menu-filter-by-keyword
Filter package list by keyword (@code{package-menu-filter-by-keyword}).
This prompts for a keyword (e.g., @samp{games}), then shows only
packages with that keyword.

@item / n
@kindex / n @r{(Package Menu)}
@findex package-menu-filter-by-name
Filter package list by name (@code{package-menu-filter-by-name}).
This prompts for a regular expression, then shows only packages
with names matching that regexp.

@item / s
@kindex / s @r{(Package Menu)}
@findex package-menu-filter-by-status
Filter package list by status (@code{package-menu-filter-by-status}).
This prompts for one or more statuses (e.g., @samp{available}), then
shows only packages with matching status.

@item / v
@kindex / v @r{(Package Menu)}
@findex package-menu-filter-by-version
Filter package list by version (@code{package-menu-filter-by-version}).
This prompts first for one of the qualifiers @samp{<}, @samp{>} or
@samp{=}, and then a package version, and shows packages that has a
lower, equal or higher version than the one specified.

@item / /
@kindex / / @r{(Package Menu)}
@findex package-menu-filter-clear
Clear filter currently applied to the package list
(@code{package-menu-filter-clear}).
@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 Statuses
@section Package Statuses
@cindex package status

A package can have one of the following statuses:

@table @samp
@item available
The package is not installed, but can be downloaded and installed from
the package archive.

@item avail-obso
The package is available for installation, but a newer version is also
available.  Packages with this status are hidden by default.

@item built-in
The package is included in Emacs by default.  It cannot be deleted
through the package menu, and is not considered for upgrading.

@item dependency
The package was installed automatically to satisfy a dependency of
another package.

@item disabled
The package has been disabled using the @code{package-load-list}
variable.

@item external
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 @samp{built-in} packages and cannot be deleted.

@item held
The package is held, @xref{Package Installation}.

@item incompat
The package cannot be installed for some reason, for example because
it depends on uninstallable packages.

@item installed
The package is installed.

@item new
Equivalent to @samp{available}, except that the package became newly
available on the package archive after your last invocation of
@kbd{M-x list-packages}.

@item obsolete
The package is an outdated installed version; in addition to this
version of the package, a newer version is also installed.

@c @samp{unsigned} (installed, but not signed; @pxref{Package Signing}),
@end table

@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{URL} or
name of the package archive directory.  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!

@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
private/public pair of cryptographic keys, and use the private key to
create a @dfn{signature file} for each package.  With the public key, you
can use the signature files to verify the package creator and make sure
the package has not been tampered with.  Signature verification uses
@uref{https://www.gnupg.org/, the GnuPG package} via the EasyPG
interface (@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}).
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{https://pgp.mit.edu/}.
Use @kbd{M-x package-import-keyring} to import the key into Emacs.
Emacs stores package keys in the directory specified by the variable
@code{package-gnupghome-dir}, by default in the @file{gnupg}
subdirectory of @code{package-user-dir}, which causes Emacs to invoke
GnuPG with the option @samp{--homedir} when verifying signatures.
If @code{package-gnupghome-dir} is @code{nil}, GnuPG's option
@samp{--homedir} is omitted.
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}, and a usable OpenPGP
configuration is found, signed packages will be checked, but 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}.  (If the value is
@code{allow-unsigned} and no usable OpenPGP is found, this option is
treated as if its value was @code{nil}.)  If the value is @code{t}, at
least one signature must be valid; if the value is @code{all}, all of
them must be valid.

  For more information on cryptographic keys and signing,
@pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}.
Emacs comes with an interface to GNU Privacy Guard,
@pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}.

@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.

@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}.)

  Once a package is downloaded and installed, it is made available to
the current Emacs session.  Making a package available 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.

  After a package is installed, it is automatically made available by
Emacs in all subsequent sessions.  This happens at startup, before
processing the init file but after processing the early init file
(@pxref{Early Init File}).  As an exception, Emacs does not make
packages available at startup if invoked with the @samp{-q} or
@samp{--no-init-file} options (@pxref{Initial Options}).

@vindex package-enable-at-startup
  To keep Emacs from automatically making packages available at
startup, change the variable @code{package-enable-at-startup} to
@code{nil}.  You must do this in the early init file, as the variable
is read before loading the regular init file.  Currently this variable
cannot be set via Customize.

@findex package-activate-all
  If you have set @code{package-enable-at-startup} to @code{nil}, you
can still make packages available either during or after startup.  To
make installed packages available during startup, call the function
@code{package-activate-all} in your init file.  To make installed
packages available after startup, invoke the command @kbd{M-:
(package-activate-all) RET}.

@vindex package-load-list
  For finer control over which packages are made available at startup,
you can use the variable @code{package-load-list}.  Its value should
be a list.  A list element of the form @w{@code{(@var{name}
@var{version})}} tells Emacs to make available 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 make available any installed version), or
@code{nil} (which means no version; this disables the package,
preventing it from being made available).  A list element can also be
the symbol @code{all}, which means to make available 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 @w{@code{'((muse
"3.20") all)}}, then Emacs only makes available 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.

debug log:

solving aa7c7e35bb ...
found aa7c7e35bb in https://yhetil.org/emacs/73F57271-4CBE-4950-B11B-50A45E1F9D54@traduction-libre.org/ ||
	https://yhetil.org/emacs/0DE280CA-A785-4623-98B6-7C2C5EA99A86@traduction-libre.org/
found db3cf317ff in https://git.savannah.gnu.org/cgit/emacs.git
preparing index
index prepared:
100644 db3cf317ff11b14be9bd48bdbc0bc43cad6d7800	doc/emacs/package.texi

applying [1/1] https://yhetil.org/emacs/73F57271-4CBE-4950-B11B-50A45E1F9D54@traduction-libre.org/
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index db3cf317ff..aa7c7e35bb 100644

Checking patch doc/emacs/package.texi...
Applied patch doc/emacs/package.texi cleanly.

skipping https://yhetil.org/emacs/0DE280CA-A785-4623-98B6-7C2C5EA99A86@traduction-libre.org/ for aa7c7e35bb
index at:
100644 7aade39615e7bd1c15542fb370fa2eddf0e516cf	doc/emacs/package.texi

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.