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