code.delx.au - gnu-emacs/blob - doc/emacs/package.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
   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 x
 111 Download and install all packages marked with @kbd{i}, and their
 112 dependencies; also, delete all packages marked with @kbd{d}
 113 (@code{package-menu-execute}).  This also removes the marks.
 114
 115 @item r
 116 Refresh the package list (@code{package-menu-refresh}).  This also
 117 retrieves the list of available packages from the package archive
 118 again.
 119 @end table
 120
 121 @noindent
 122 For example, you can install a package by typing @kbd{i} on the line
 123 listing that package, followed by @kbd{x}.
 124
 125 @node Package Installation
 126 @section Package Installation
 127
 128 @findex package-install
 129   Packages are most conveniently installed using the package menu
 130 (@pxref{Package Menu}), but you can also use the command @kbd{M-x
 131 package-install}.  This prompts for the name of a package with the
 132 @samp{available} status, then downloads and installs it.
 133
 134 @cindex package requirements
 135   A package may @dfn{require} certain other packages to be installed,
 136 because it relies on functionality provided by them.  When Emacs
 137 installs such a package, it also automatically downloads and installs
 138 any required package that is not already installed.  (If a required
 139 package is somehow unavailable, Emacs signals an error and stops
 140 installation.)  A package's requirements list is shown in its help
 141 buffer.
 142
 143 @vindex package-archives
 144   By default, packages are downloaded from a single package archive
 145 maintained by the Emacs developers.  This is controlled by the
 146 variable @code{package-archives}, whose value is a list of package
 147 archives known to Emacs.  Each list element must have the form
 148 @code{(@var{id} . @var{location})}, where @var{id} is the name of a
 149 package archive and @var{location} is the @acronym{HTTP} address or
 150 directory name of the package archive.  You can alter this list if you
 151 wish to use third party package archives---but do so at your own risk,
 152 and use only third parties that you think you can trust!
 153
 154   Once a package is downloaded and installed, it takes effect in the
 155 current Emacs session.  What ``taking effect'' means depends on the
 156 package; most packages just make some new commands available, while
 157 others have more wide-ranging effects on the Emacs session.  For such
 158 information, consult the package's help buffer.
 159
 160   By default, Emacs also automatically loads all installed packages
 161 (causing them to ``take effect'') in subsequent Emacs sessions.  This
 162 happens at startup, after processing the init file (@pxref{Init
 163 File}).  As an exception, Emacs does not load packages at startup if
 164 invoked with the @samp{-q} or @samp{--no-init-file} options
 165 (@pxref{Initial Options}).
 166
 167 @vindex package-enable-at-startup
 168 @findex package-initialize
 169   To disable automatic package loading, change the variable
 170 @code{package-enable-at-startup} to @code{nil}.  If you do this, you
 171 can use the command @kbd{M-x package-initialize} to load your
 172 packages.
 173
 174 @vindex package-load-list
 175   For finer control over package loading, you can use the variable
 176 @code{package-load-list}.  Its value should be a list.  A list element
 177 of the form @code{(@var{name} @var{version})} tells Emacs to load
 178 version @var{version} of the package named @var{name}.  Here,
 179 @var{version} should be a version string (corresponding to a specific
 180 version of the package), or @code{t} (which means to load any
 181 installed version), or @code{nil} (which means no version; this
 182 ``disables'' the package, preventing it from being loaded).  A list
 183 element can also be the symbol @code{all}, which means to load the
 184 latest installed version of any package not named by the other list
 185 elements.  The default value is just @code{'(all)}.
 186
 187   For example, if you set @code{package-load-list} to @code{'((muse
 188 "3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse}
 189 package, plus any installed version of packages other than
 190 @samp{muse}.  Any other version of @samp{muse} that happens to be
 191 installed will be ignored.  The @samp{muse} package will be listed in
 192 the package menu with the @samp{held} status.
 193
 194 @node Package Files
 195 @section Package Files and Directory Layout
 196 @cindex package directory
 197
 198 @cindex package file
 199 @findex package-install-file
 200   Each package is downloaded from the package archive in the form of a
 201 single @dfn{package file}---either an Emacs Lisp source file, or a tar
 202 file containing multiple Emacs Lisp source and other files.  Package
 203 files are automatically retrieved, processed, and disposed of by the
 204 Emacs commands that install packages.  Normally, you will not need to
 205 deal directly with them, unless you are making a package
 206 (@pxref{Packaging,,,elisp, The Emacs Lisp Reference Manual}).  Should
 207 you ever need to install a package directly from a package file, use
 208 the command @kbd{M-x package-install-file}.
 209
 210 @vindex package-user-dir
 211   Once installed, the contents of a package are placed in a
 212 subdirectory of @file{~/.emacs.d/elpa/} (you can change the name of
 213 that directory by changing the variable @code{package-user-dir}).  The
 214 package subdirectory is named @file{@var{name}-@var{version}}, where
 215 @var{name} is the package name and @var{version} is its version
 216 string.
 217
 218 @cindex system-wide packages
 219 @vindex package-directory-list
 220   In addition to @code{package-user-dir}, Emacs looks for installed
 221 packages in the directories listed in @code{package-directory-list}.
 222 These directories are meant for system administrators to make Emacs
 223 packages available system-wide; Emacs itself never installs packages
 224 there.  The package subdirectories for @code{package-directory-list}
 225 are laid out in the same way as in @code{package-user-dir}.
 226
 227   Deleting a package (@pxref{Package Menu}) involves deleting the
 228 corresponding package subdirectory.  This only works for packages
 229 installed in @code{package-user-dir}; if told to act on a package in a
 230 system-wide package directory, the deletion command signals an error.