doc/emacs/package.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
   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
  23 name of a package, and displays a help buffer describing that
  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
 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
 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
 122 Refresh the package list (@code{package-menu-refresh}).  This also
 123 retrieves the list of available packages from the package archive
 124 again.
 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
 160   Once a package is downloaded and installed, it takes effect in the
 161 current Emacs session.  What ``taking effect'' means depends on the
 162 package; most packages just make some new commands available, while
 163 others have more wide-ranging effects on the Emacs session.  For such
 164 information, consult the package's help buffer.
 165
 166   By default, Emacs also automatically loads all installed packages
 167 (causing them to ``take effect'') in subsequent Emacs sessions.  This
 168 happens at startup, after processing the init file (@pxref{Init
 169 File}).  As an exception, Emacs does not load packages at startup if
 170 invoked with the @samp{-q} or @samp{--no-init-file} options
 171 (@pxref{Initial Options}).
 172
 173 @vindex package-enable-at-startup
 174 @findex package-initialize
 175   To disable automatic package loading, change the variable
 176 @code{package-enable-at-startup} to @code{nil}.  If you do this, you
 177 can use the command @kbd{M-x package-initialize} to load your
 178 packages.
 179
 180 @vindex package-load-list
 181   For finer control over package loading, you can use the variable
 182 @code{package-load-list}.  Its value should be a list.  A list element
 183 of the form @code{(@var{name} @var{version})} tells Emacs to load
 184 version @var{version} of the package named @var{name}.  Here,
 185 @var{version} should be a version string (corresponding to a specific
 186 version of the package), or @code{t} (which means to load any
 187 installed version), or @code{nil} (which means no version; this
 188 ``disables'' the package, preventing it from being loaded).  A list
 189 element can also be the symbol @code{all}, which means to load the
 190 latest installed version of any package not named by the other list
 191 elements.  The default value is just @code{'(all)}.
 192
 193   For example, if you set @code{package-load-list} to @code{'((muse
 194 "3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse}
 195 package, plus any installed version of packages other than
 196 @samp{muse}.  Any other version of @samp{muse} that happens to be
 197 installed will be ignored.  The @samp{muse} package will be listed in
 198 the package menu with the @samp{held} status.
 199
 200 @node Package Files
 201 @section Package Files and Directory Layout
 202 @cindex package directory
 203
 204 @cindex package file
 205 @findex package-install-file
 206   Each package is downloaded from the package archive in the form of a
 207 single @dfn{package file}---either an Emacs Lisp source file, or a tar
 208 file containing multiple Emacs Lisp source and other files.  Package
 209 files are automatically retrieved, processed, and disposed of by the
 210 Emacs commands that install packages.  Normally, you will not need to
 211 deal directly with them, unless you are making a package
 212 (@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}).  Should
 213 you ever need to install a package directly from a package file, use
 214 the command @kbd{M-x package-install-file}.
 215
 216 @vindex package-user-dir
 217   Once installed, the contents of a package are placed in a
 218 subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of
 219 that directory by changing the variable @code{package-user-dir}).  The
 220 package subdirectory is named @file{@var{name}-@var{version}}, where
 221 @var{name} is the package name and @var{version} is its version
 222 string.
 223
 224 @cindex system-wide packages
 225 @vindex package-directory-list
 226   In addition to @code{package-user-dir}, Emacs looks for installed
 227 packages in the directories listed in @code{package-directory-list}.
 228 These directories are meant for system administrators to make Emacs
 229 packages available system-wide; Emacs itself never installs packages
 230 there.  The package subdirectories for @code{package-directory-list}
 231 are laid out in the same way as in @code{package-user-dir}.
 232
 233   Deleting a package (@pxref{Package Menu}) involves deleting the
 234 corresponding package subdirectory.  This only works for packages
 235 installed in @code{package-user-dir}; if told to act on a package in a
 236 system-wide package directory, the deletion command signals an error.