Commit | Line | Data |
---|---|---|
d43f5a42 | 1 | @c This is part of the Emacs manual. |
acaf905b | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 |
d43f5a42 CY |
3 | @c Free Software Foundation, Inc. |
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 | ||
17 | @kbd{M-x list-packages} brings up a buffer named @samp{*Packages*} | |
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 | |
55 | The package name (e.g. @samp{auctex}). | |
56 | ||
57 | @item | |
58 | The package's version number (e.g. @samp{11.86}). | |
59 | ||
60 | @item | |
61 | The package's status---normally one of @samp{available} (can be | |
62 | downloaded from the package archive), @samp{installed}, or | |
63 | @samp{built-in} (included in Emacs by default). | |
64 | ||
65 | In some instances, the status can be @samp{held}, @samp{disabled}, or | |
66 | @samp{obsolete}. @xref{Package Installation}. | |
67 | ||
68 | @item | |
69 | A short description of the package. | |
70 | @end itemize | |
71 | ||
72 | @noindent | |
73 | The @code{list-packages} command accesses the network, to retrieve the | |
74 | list of available packages from the package archive server. If the | |
75 | network is unavailable, it falls back on the most recently retrieved | |
76 | list. | |
77 | ||
78 | The following commands are available in the package menu: | |
79 | ||
80 | @table @kbd | |
81 | @item h | |
82 | Print a short message summarizing how to use the package menu | |
83 | (@code{package-menu-quick-help}). | |
84 | ||
85 | @item ? | |
86 | @itemx @key{RET} | |
87 | Display a help buffer for the package on the current line | |
88 | (@code{package-menu-describe-package}), similar to the help window | |
89 | displayed by the @kbd{C-h P} command (@pxref{Packages}). | |
90 | ||
91 | @item i | |
92 | Mark the package on the current line for installation | |
93 | (@code{package-menu-mark-install}). If the package status is | |
94 | @samp{available}, this adds an @samp{I} character to the start of the | |
95 | line; typing @kbd{x} (see below) will download and install the | |
96 | package. | |
97 | ||
98 | @item d | |
99 | Mark the package on the current line for deletion | |
100 | (@code{package-menu-mark-delete}). If the package status is | |
101 | @samp{installed}, this adds a @samp{D} character to the start of the | |
102 | line; typing @kbd{x} (see below) will delete the package. | |
103 | @xref{Package Files}, for information about what package deletion | |
104 | entails. | |
105 | ||
106 | @item u | |
107 | Remove any installation or deletion mark previously added to the | |
108 | current line by an @kbd{i} or @kbd{d} command. | |
109 | ||
92fa95ad CY |
110 | @item U |
111 | Mark all package with a newer available version for ``upgrading'' | |
112 | (@code{package-menu-mark-upgrades}). This places an installation mark | |
113 | on the new available versions, and a deletion mark on the old | |
114 | installed versions. | |
115 | ||
d43f5a42 CY |
116 | @item x |
117 | Download and install all packages marked with @kbd{i}, and their | |
118 | dependencies; also, delete all packages marked with @kbd{d} | |
119 | (@code{package-menu-execute}). This also removes the marks. | |
120 | ||
121 | @item r | |
b0d7d8af CY |
122 | Refresh the package list (@code{package-menu-refresh}). This fetches |
123 | the list of available packages from the package archive again, and | |
124 | recomputes the package list. | |
d43f5a42 CY |
125 | @end table |
126 | ||
127 | @noindent | |
128 | For example, you can install a package by typing @kbd{i} on the line | |
129 | listing that package, followed by @kbd{x}. | |
130 | ||
131 | @node Package Installation | |
132 | @section Package Installation | |
133 | ||
134 | @findex package-install | |
135 | Packages are most conveniently installed using the package menu | |
136 | (@pxref{Package Menu}), but you can also use the command @kbd{M-x | |
137 | package-install}. This prompts for the name of a package with the | |
138 | @samp{available} status, then downloads and installs it. | |
139 | ||
140 | @cindex package requirements | |
141 | A package may @dfn{require} certain other packages to be installed, | |
142 | because it relies on functionality provided by them. When Emacs | |
143 | installs such a package, it also automatically downloads and installs | |
144 | any required package that is not already installed. (If a required | |
145 | package is somehow unavailable, Emacs signals an error and stops | |
146 | installation.) A package's requirements list is shown in its help | |
147 | buffer. | |
148 | ||
149 | @vindex package-archives | |
150 | By default, packages are downloaded from a single package archive | |
151 | maintained by the Emacs developers. This is controlled by the | |
152 | variable @code{package-archives}, whose value is a list of package | |
153 | archives known to Emacs. Each list element must have the form | |
154 | @code{(@var{id} . @var{location})}, where @var{id} is the name of a | |
155 | package archive and @var{location} is the @acronym{HTTP} address or | |
156 | directory name of the package archive. You can alter this list if you | |
157 | wish to use third party package archives---but do so at your own risk, | |
158 | and use only third parties that you think you can trust! | |
159 | ||
986bd52a CY |
160 | Once a package is downloaded and installed, it is @dfn{loaded} into |
161 | the current Emacs session. Loading a package is not quite the same as | |
162 | loading a Lisp library (@pxref{Lisp Libraries}); its effect varies | |
163 | from package to package. Most packages just make some new commands | |
164 | available, while others have more wide-ranging effects on the Emacs | |
165 | session. For such information, consult the package's help buffer. | |
166 | ||
167 | By default, Emacs also automatically loads all installed packages in | |
168 | subsequent Emacs sessions. This happens at startup, after processing | |
169 | the init file (@pxref{Init File}). As an exception, Emacs does not | |
170 | load packages at startup if invoked with the @samp{-q} or | |
171 | @samp{--no-init-file} options (@pxref{Initial Options}). | |
d43f5a42 CY |
172 | |
173 | @vindex package-enable-at-startup | |
d43f5a42 | 174 | To disable automatic package loading, change the variable |
986bd52a CY |
175 | @code{package-enable-at-startup} to @code{nil}. |
176 | ||
177 | @findex package-initialize | |
178 | The reason automatic package loading occurs after loading the init | |
179 | file is that user options only receive their customized values after | |
180 | loading the init file, including user options which affect the | |
181 | packaging system. In some circumstances, you may want to load | |
182 | packages explicitly in your init file (usually because some other code | |
183 | in your init file depends on a package). In that case, your init file | |
184 | should call the function @code{package-initialize}. It is up to you | |
185 | to ensure that relevant user options, such as @code{package-load-list} | |
186 | (see below), are set up prior to the @code{package-initialize} call. | |
187 | You should also set @code{package-enable-at-startup} to @code{nil}, to | |
188 | avoid loading the packages again after processing the init file. | |
189 | Alternatively, you may choose to completely inhibit package loading at | |
190 | startup, and invoke the command @kbd{M-x package-initialize} to load | |
191 | your packages manually. | |
d43f5a42 CY |
192 | |
193 | @vindex package-load-list | |
194 | For finer control over package loading, you can use the variable | |
195 | @code{package-load-list}. Its value should be a list. A list element | |
196 | of the form @code{(@var{name} @var{version})} tells Emacs to load | |
197 | version @var{version} of the package named @var{name}. Here, | |
198 | @var{version} should be a version string (corresponding to a specific | |
199 | version of the package), or @code{t} (which means to load any | |
200 | installed version), or @code{nil} (which means no version; this | |
201 | ``disables'' the package, preventing it from being loaded). A list | |
202 | element can also be the symbol @code{all}, which means to load the | |
203 | latest installed version of any package not named by the other list | |
204 | elements. The default value is just @code{'(all)}. | |
205 | ||
206 | For example, if you set @code{package-load-list} to @code{'((muse | |
207 | "3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse} | |
208 | package, plus any installed version of packages other than | |
209 | @samp{muse}. Any other version of @samp{muse} that happens to be | |
210 | installed will be ignored. The @samp{muse} package will be listed in | |
211 | the package menu with the @samp{held} status. | |
212 | ||
213 | @node Package Files | |
214 | @section Package Files and Directory Layout | |
215 | @cindex package directory | |
216 | ||
217 | @cindex package file | |
218 | @findex package-install-file | |
219 | Each package is downloaded from the package archive in the form of a | |
220 | single @dfn{package file}---either an Emacs Lisp source file, or a tar | |
221 | file containing multiple Emacs Lisp source and other files. Package | |
222 | files are automatically retrieved, processed, and disposed of by the | |
223 | Emacs commands that install packages. Normally, you will not need to | |
224 | deal directly with them, unless you are making a package | |
225 | (@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}). Should | |
226 | you ever need to install a package directly from a package file, use | |
227 | the command @kbd{M-x package-install-file}. | |
228 | ||
229 | @vindex package-user-dir | |
230 | Once installed, the contents of a package are placed in a | |
231 | subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of | |
232 | that directory by changing the variable @code{package-user-dir}). The | |
233 | package subdirectory is named @file{@var{name}-@var{version}}, where | |
234 | @var{name} is the package name and @var{version} is its version | |
235 | string. | |
236 | ||
237 | @cindex system-wide packages | |
238 | @vindex package-directory-list | |
239 | In addition to @code{package-user-dir}, Emacs looks for installed | |
240 | packages in the directories listed in @code{package-directory-list}. | |
241 | These directories are meant for system administrators to make Emacs | |
242 | packages available system-wide; Emacs itself never installs packages | |
243 | there. The package subdirectories for @code{package-directory-list} | |
244 | are laid out in the same way as in @code{package-user-dir}. | |
245 | ||
246 | Deleting a package (@pxref{Package Menu}) involves deleting the | |
247 | corresponding package subdirectory. This only works for packages | |
248 | installed in @code{package-user-dir}; if told to act on a package in a | |
249 | system-wide package directory, the deletion command signals an error. |