Commit | Line | Data |
---|---|---|
d43f5a42 | 1 | @c This is part of the Emacs manual. |
ba318903 | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software |
ab422c4d | 3 | @c Foundation, Inc. |
d43f5a42 CY |
4 | @c See file emacs.texi for copying conditions. |
5 | @node Packages | |
6 | @chapter Emacs Lisp Packages | |
7 | @cindex Package | |
8 | @cindex Emacs Lisp package archive | |
9 | @cindex Package archive | |
10 | @cindex Emacs Lisp package | |
11 | ||
12 | Emacs includes a facility that lets you easily download and install | |
13 | @dfn{packages} that implement additional features. Each package is a | |
14 | separate Emacs Lisp program, sometimes including other components such | |
15 | as an Info manual. | |
16 | ||
1c64e6ed | 17 | @kbd{M-x list-packages} brings up a buffer named @file{*Packages*} |
d43f5a42 CY |
18 | with a list of all packages. You can install or uninstall packages |
19 | via this buffer. @xref{Package Menu}. | |
20 | ||
21 | @findex describe-package | |
22 | The command @kbd{C-h P} (@code{describe-package}) prompts for the | |
b0d7d8af | 23 | name of a package, and displays a help buffer describing the |
d43f5a42 CY |
24 | attributes of the package and the features that it implements. |
25 | ||
26 | By default, Emacs downloads packages from a @dfn{package archive} | |
27 | maintained by the Emacs developers and hosted by the GNU project. | |
28 | Optionally, you can also download packages from archives maintained by | |
29 | third parties. @xref{Package Installation}. | |
30 | ||
31 | For information about turning an Emacs Lisp program into an | |
32 | installable package, @xref{Packaging,,,elisp, The Emacs Lisp Reference | |
33 | Manual}. For information about finding third-party packages and other | |
34 | Emacs Lisp extensions, @xref{Packages that do not come with | |
35 | Emacs,,,efaq, GNU Emacs FAQ}. | |
36 | ||
37 | @menu | |
38 | * Package Menu:: Buffer for viewing and managing packages. | |
39 | * Package Installation:: Options for package installation. | |
40 | * Package Files:: Where packages are installed. | |
41 | @end menu | |
42 | ||
43 | @node Package Menu | |
44 | @section The Package Menu Buffer | |
45 | @cindex package menu | |
46 | @cindex built-in package | |
47 | @findex list-packages | |
48 | ||
49 | The command @kbd{M-x list-packages} brings up the @dfn{package menu}. | |
50 | This is a buffer listing all the packages that Emacs knows about, one | |
51 | on each line, with the following information: | |
52 | ||
53 | @itemize @bullet | |
54 | @item | |
1df7defd | 55 | The package name (e.g., @samp{auctex}). |
d43f5a42 CY |
56 | |
57 | @item | |
1df7defd | 58 | The package's version number (e.g., @samp{11.86}). |
d43f5a42 CY |
59 | |
60 | @item | |
61 | The package's status---normally one of @samp{available} (can be | |
e1b3f35f GM |
62 | downloaded from the package archive), @samp{installed}, |
63 | @samp{unsigned} (installed, but not signed; @pxref{Package Signing}), | |
64 | or @samp{built-in} (included in Emacs by default). | |
d43f5a42 | 65 | |
05b621a6 CY |
66 | The status can also be @samp{new}. This is equivalent to |
67 | @samp{available}, except that it means the package became newly | |
68 | available on the package archive after your last invocation of | |
69 | @kbd{M-x list-packages}. In other instances, a package may have the | |
70 | status @samp{held}, @samp{disabled}, or @samp{obsolete}. | |
71 | @xref{Package Installation}. | |
d43f5a42 CY |
72 | |
73 | @item | |
74 | A short description of the package. | |
75 | @end itemize | |
76 | ||
77 | @noindent | |
78 | The @code{list-packages} command accesses the network, to retrieve the | |
79 | list of available packages from the package archive server. If the | |
80 | network is unavailable, it falls back on the most recently retrieved | |
81 | list. | |
82 | ||
83 | The following commands are available in the package menu: | |
84 | ||
85 | @table @kbd | |
86 | @item h | |
87 | Print a short message summarizing how to use the package menu | |
88 | (@code{package-menu-quick-help}). | |
89 | ||
90 | @item ? | |
91 | @itemx @key{RET} | |
92 | Display a help buffer for the package on the current line | |
93 | (@code{package-menu-describe-package}), similar to the help window | |
94 | displayed by the @kbd{C-h P} command (@pxref{Packages}). | |
95 | ||
96 | @item i | |
97 | Mark the package on the current line for installation | |
98 | (@code{package-menu-mark-install}). If the package status is | |
99 | @samp{available}, this adds an @samp{I} character to the start of the | |
100 | line; typing @kbd{x} (see below) will download and install the | |
101 | package. | |
102 | ||
103 | @item d | |
104 | Mark the package on the current line for deletion | |
105 | (@code{package-menu-mark-delete}). If the package status is | |
106 | @samp{installed}, this adds a @samp{D} character to the start of the | |
107 | line; typing @kbd{x} (see below) will delete the package. | |
108 | @xref{Package Files}, for information about what package deletion | |
109 | entails. | |
110 | ||
111 | @item u | |
112 | Remove any installation or deletion mark previously added to the | |
113 | current line by an @kbd{i} or @kbd{d} command. | |
114 | ||
92fa95ad CY |
115 | @item U |
116 | Mark all package with a newer available version for ``upgrading'' | |
117 | (@code{package-menu-mark-upgrades}). This places an installation mark | |
118 | on the new available versions, and a deletion mark on the old | |
119 | installed versions. | |
120 | ||
d43f5a42 CY |
121 | @item x |
122 | Download and install all packages marked with @kbd{i}, and their | |
123 | dependencies; also, delete all packages marked with @kbd{d} | |
124 | (@code{package-menu-execute}). This also removes the marks. | |
125 | ||
126 | @item r | |
b0d7d8af CY |
127 | Refresh the package list (@code{package-menu-refresh}). This fetches |
128 | the list of available packages from the package archive again, and | |
129 | recomputes the package list. | |
a215930c GM |
130 | |
131 | @item f | |
132 | Filter the package list (@code{package-menu-filter}). This prompts | |
133 | for a keyword (e.g., @samp{games}), then shows only the packages | |
134 | that relate to that keyword. To restore the full package list, | |
135 | type @kbd{q}. | |
d43f5a42 CY |
136 | @end table |
137 | ||
138 | @noindent | |
139 | For example, you can install a package by typing @kbd{i} on the line | |
140 | listing that package, followed by @kbd{x}. | |
141 | ||
142 | @node Package Installation | |
143 | @section Package Installation | |
144 | ||
145 | @findex package-install | |
146 | Packages are most conveniently installed using the package menu | |
147 | (@pxref{Package Menu}), but you can also use the command @kbd{M-x | |
148 | package-install}. This prompts for the name of a package with the | |
149 | @samp{available} status, then downloads and installs it. | |
150 | ||
151 | @cindex package requirements | |
152 | A package may @dfn{require} certain other packages to be installed, | |
153 | because it relies on functionality provided by them. When Emacs | |
154 | installs such a package, it also automatically downloads and installs | |
155 | any required package that is not already installed. (If a required | |
156 | package is somehow unavailable, Emacs signals an error and stops | |
157 | installation.) A package's requirements list is shown in its help | |
158 | buffer. | |
159 | ||
160 | @vindex package-archives | |
161 | By default, packages are downloaded from a single package archive | |
162 | maintained by the Emacs developers. This is controlled by the | |
163 | variable @code{package-archives}, whose value is a list of package | |
164 | archives known to Emacs. Each list element must have the form | |
165 | @code{(@var{id} . @var{location})}, where @var{id} is the name of a | |
166 | package archive and @var{location} is the @acronym{HTTP} address or | |
167 | directory name of the package archive. You can alter this list if you | |
168 | wish to use third party package archives---but do so at your own risk, | |
169 | and use only third parties that you think you can trust! | |
170 | ||
e1b3f35f GM |
171 | @anchor{Package Signing} |
172 | @cindex package security | |
173 | @cindex package signing | |
174 | The maintainers of package archives can increase the trust that you | |
175 | can have in their packages by @dfn{signing} them. They generate a | |
136c315e | 176 | private/public pair of cryptographic keys, and use the private key to |
e1b3f35f GM |
177 | create a @dfn{signature file} for each package. With the public key, you |
178 | can use the signature files to verify who created the package, and | |
179 | that it has not been modified. A valid signature is not a cast-iron | |
180 | guarantee that a package is not malicious, so you should still | |
181 | exercise caution. Package archives should provide instructions | |
182 | on how you can obtain their public key. One way is to download the | |
183 | key from a server such as @url{http://pgp.mit.edu/}. | |
184 | Use @kbd{M-x package-import-keyring} to import the key into Emacs. | |
185 | Emacs stores package keys in the @file{gnupg} subdirectory | |
186 | of @code{package-user-dir}. | |
187 | @c Uncomment this if it becomes true. | |
188 | @ignore | |
189 | The public key for the GNU package archive is distributed with Emacs, | |
190 | in the @file{etc/package-keyring.gpg}. Emacs uses it automatically. | |
191 | @end ignore | |
192 | ||
193 | @vindex package-check-signature | |
194 | @vindex package-unsigned-archives | |
195 | If the user option @code{package-check-signature} is non-@code{nil}, | |
196 | Emacs attempts to verify signatures when you install packages. If the | |
197 | option has the value @code{allow-unsigned}, you can still install a | |
198 | package that is not signed. If you use some archives that do not sign | |
199 | their packages, you can add them to the list @code{package-unsigned-archives}. | |
200 | ||
136c315e | 201 | For more information on cryptographic keys and signing, |
e1b3f35f GM |
202 | @pxref{Top,, Top, gnupg, The GNU Privacy Guard Manual}. |
203 | Emacs comes with an interface to GNU Privacy Guard, | |
204 | @pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. | |
205 | ||
e7477c9f GM |
206 | @vindex package-pinned-packages |
207 | If you have more than one package archive enabled, and some of them | |
208 | offer different versions of the same package, you may find the option | |
209 | @code{package-pinned-packages} useful. You can add package/archive | |
210 | pairs to this list, to ensure that the specified package is only ever | |
211 | downloaded from the specified archive. | |
212 | ||
986bd52a CY |
213 | Once a package is downloaded and installed, it is @dfn{loaded} into |
214 | the current Emacs session. Loading a package is not quite the same as | |
215 | loading a Lisp library (@pxref{Lisp Libraries}); its effect varies | |
216 | from package to package. Most packages just make some new commands | |
217 | available, while others have more wide-ranging effects on the Emacs | |
218 | session. For such information, consult the package's help buffer. | |
219 | ||
220 | By default, Emacs also automatically loads all installed packages in | |
221 | subsequent Emacs sessions. This happens at startup, after processing | |
222 | the init file (@pxref{Init File}). As an exception, Emacs does not | |
223 | load packages at startup if invoked with the @samp{-q} or | |
224 | @samp{--no-init-file} options (@pxref{Initial Options}). | |
d43f5a42 CY |
225 | |
226 | @vindex package-enable-at-startup | |
d43f5a42 | 227 | To disable automatic package loading, change the variable |
986bd52a CY |
228 | @code{package-enable-at-startup} to @code{nil}. |
229 | ||
230 | @findex package-initialize | |
231 | The reason automatic package loading occurs after loading the init | |
232 | file is that user options only receive their customized values after | |
233 | loading the init file, including user options which affect the | |
234 | packaging system. In some circumstances, you may want to load | |
235 | packages explicitly in your init file (usually because some other code | |
236 | in your init file depends on a package). In that case, your init file | |
237 | should call the function @code{package-initialize}. It is up to you | |
238 | to ensure that relevant user options, such as @code{package-load-list} | |
239 | (see below), are set up prior to the @code{package-initialize} call. | |
240 | You should also set @code{package-enable-at-startup} to @code{nil}, to | |
241 | avoid loading the packages again after processing the init file. | |
242 | Alternatively, you may choose to completely inhibit package loading at | |
243 | startup, and invoke the command @kbd{M-x package-initialize} to load | |
244 | your packages manually. | |
d43f5a42 CY |
245 | |
246 | @vindex package-load-list | |
247 | For finer control over package loading, you can use the variable | |
248 | @code{package-load-list}. Its value should be a list. A list element | |
249 | of the form @code{(@var{name} @var{version})} tells Emacs to load | |
250 | version @var{version} of the package named @var{name}. Here, | |
251 | @var{version} should be a version string (corresponding to a specific | |
252 | version of the package), or @code{t} (which means to load any | |
253 | installed version), or @code{nil} (which means no version; this | |
254 | ``disables'' the package, preventing it from being loaded). A list | |
255 | element can also be the symbol @code{all}, which means to load the | |
256 | latest installed version of any package not named by the other list | |
257 | elements. The default value is just @code{'(all)}. | |
258 | ||
259 | For example, if you set @code{package-load-list} to @code{'((muse | |
260 | "3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse} | |
261 | package, plus any installed version of packages other than | |
262 | @samp{muse}. Any other version of @samp{muse} that happens to be | |
263 | installed will be ignored. The @samp{muse} package will be listed in | |
264 | the package menu with the @samp{held} status. | |
265 | ||
266 | @node Package Files | |
267 | @section Package Files and Directory Layout | |
268 | @cindex package directory | |
269 | ||
270 | @cindex package file | |
271 | @findex package-install-file | |
272 | Each package is downloaded from the package archive in the form of a | |
273 | single @dfn{package file}---either an Emacs Lisp source file, or a tar | |
274 | file containing multiple Emacs Lisp source and other files. Package | |
275 | files are automatically retrieved, processed, and disposed of by the | |
276 | Emacs commands that install packages. Normally, you will not need to | |
277 | deal directly with them, unless you are making a package | |
278 | (@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}). Should | |
279 | you ever need to install a package directly from a package file, use | |
280 | the command @kbd{M-x package-install-file}. | |
281 | ||
282 | @vindex package-user-dir | |
283 | Once installed, the contents of a package are placed in a | |
284 | subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of | |
285 | that directory by changing the variable @code{package-user-dir}). The | |
286 | package subdirectory is named @file{@var{name}-@var{version}}, where | |
287 | @var{name} is the package name and @var{version} is its version | |
288 | string. | |
289 | ||
290 | @cindex system-wide packages | |
291 | @vindex package-directory-list | |
292 | In addition to @code{package-user-dir}, Emacs looks for installed | |
293 | packages in the directories listed in @code{package-directory-list}. | |
294 | These directories are meant for system administrators to make Emacs | |
295 | packages available system-wide; Emacs itself never installs packages | |
296 | there. The package subdirectories for @code{package-directory-list} | |
297 | are laid out in the same way as in @code{package-user-dir}. | |
298 | ||
299 | Deleting a package (@pxref{Package Menu}) involves deleting the | |
300 | corresponding package subdirectory. This only works for packages | |
301 | installed in @code{package-user-dir}; if told to act on a package in a | |
302 | system-wide package directory, the deletion command signals an error. |